Godot MCP

Language: English | 简体中文

Open-source Godot MCP server that lets AI assistants (Claude Code, Cursor, Codex, and more) control the Godot 4 editor directly through the Model Context Protocol (MCP).

AI client  ←—stdio/MCP—→  Node.js server  ←—WebSocket:6505—→  Godot editor plugin

Overview

Core features

• UndoRedo integration — node add/remove/edit and property changes go through the editor undo stack
• Smart type parsing — strings like Vector2(100, 200), #ff0000, Color(1,0,0) are converted automatically
• Reconnect with backoff — exponential backoff on the plugin side (1s → 60s)
• Heartbeat — bidirectional ping/pong to keep the WebSocket alive
• JSON-RPC 2.0 — standard protocol between the Godot plugin and the Node.js server

Tool categories

173 MCP tools across 26 categories:

Project: get_project_info · get_filesystem_tree · search_files · get_project_settings · set_project_setting · uid_to_project_path · project_path_to_uid

Scene: get_scene_tree · get_scene_file_content · create_scene · open_scene · delete_scene · add_scene_instance · play_scene · stop_scene · save_scene · get_scene_exports

Node: add_node · delete_node · duplicate_node · move_node · update_property · get_node_properties · add_resource · set_anchor_preset · rename_node · connect_signal · disconnect_signal · get_node_groups · set_node_groups · find_nodes_in_group

Script: list_scripts · read_script · create_script · edit_script · attach_script · get_open_scripts · validate_script · search_in_files

Editor: get_editor_errors · get_editor_screenshot · get_game_screenshot · execute_editor_script · clear_output · get_signals · reload_plugin · reload_project · get_output_log · get_editor_camera · set_editor_camera · set_auto_dismiss · compare_screenshots

Input: simulate_key · simulate_mouse_click · simulate_mouse_move · simulate_action · simulate_sequence · get_input_actions · set_input_action

Runtime: get_game_scene_tree · get_game_node_properties · set_game_node_property · execute_game_script · capture_frames · monitor_properties · start_recording · stop_recording · replay_recording · find_nodes_by_script · get_autoload · batch_get_properties · find_ui_elements · click_button_by_text · wait_for_node · find_nearby_nodes · navigate_to · move_to · watch_signals

Animation: list_animations · create_animation · add_animation_track · set_animation_keyframe · get_animation_info · remove_animation

TileMap: tilemap_set_cell · tilemap_fill_rect · tilemap_get_cell · tilemap_clear · tilemap_get_info · tilemap_get_used_cells

Theme/UI: create_theme · set_theme_color · set_theme_constant · set_theme_font_size · set_theme_stylebox · get_theme_info · setup_control

Profiling: get_performance_monitors · get_editor_performance

Batch/Refactor: find_nodes_by_type · find_signal_connections · batch_set_property · find_node_references · get_scene_dependencies · cross_scene_set_property · find_script_references · detect_circular_dependencies · batch_add_nodes

Shader: create_shader · read_shader · edit_shader · assign_shader_material · set_shader_param · get_shader_params

Export: list_export_presets · export_project · get_export_info

Resource: read_resource · edit_resource · create_resource · get_resource_preview · add_autoload · remove_autoload

Physics: setup_physics_body · setup_collision · set_physics_layers · get_physics_layers · get_collision_info · add_raycast

3D Scene: add_mesh_instance · setup_camera_3d · setup_lighting · setup_environment · add_gridmap · set_material_3d

Particle: create_particles · set_particle_material · set_particle_color_gradient · apply_particle_preset · get_particle_info

Navigation: setup_navigation_region · setup_navigation_agent · bake_navigation_mesh · set_navigation_layers · get_navigation_info · get_navigation_path

Audio: add_audio_player · add_audio_bus · add_audio_bus_effect · set_audio_bus · get_audio_bus_layout · get_audio_info

AnimationTree: create_animation_tree · get_animation_tree_structure · set_tree_parameter · add_state_machine_state · remove_state_machine_state · add_state_machine_transition · remove_state_machine_transition · set_blend_tree_node

Analysis: analyze_scene_complexity · analyze_signal_flow · find_unused_resources · get_project_statistics

Testing/QA: run_test_scenario · assert_node_state · assert_screen_text · run_stress_test · get_test_report

Android: list_android_devices · deploy_to_android · get_android_build_info · get_android_preset_info

Project structure

godot-mcp/
├── addons/godot_mcp/              # Godot editor plugin (copy into your project)
│   ├── plugin.gd                  # Plugin entry; injects autoloads
│   ├── plugin.cfg
│   ├── websocket_client.gd        # WebSocket client + JSON-RPC dispatch
│   ├── command_router.gd          # Command router; registers all handlers
│   ├── commands/                  # 24 command modules (173 tool implementations)
│   │   ├── base_commands.gd       # Base class: Undo, runtime IPC, screenshots, etc.
│   │   ├── project_commands.gd
│   │   ├── scene_commands.gd
│   │   ├── node_commands.gd
│   │   ├── script_commands.gd
│   │   ├── editor_commands.gd
│   │   ├── input_commands.gd
│   │   ├── runtime_commands.gd
│   │   ├── animation_commands.gd
│   │   ├── tilemap_commands.gd
│   │   ├── theme_commands.gd
│   │   ├── profiling_commands.gd
│   │   ├── batch_commands.gd
│   │   ├── shader_commands.gd
│   │   ├── export_commands.gd
│   │   ├── resource_commands.gd
│   │   ├── physics_commands.gd
│   │   ├── scene_3d_commands.gd
│   │   ├── particle_commands.gd
│   │   ├── navigation_commands.gd
│   │   ├── audio_commands.gd
│   │   ├── animation_tree_commands.gd
│   │   ├── analysis_commands.gd
│   │   ├── test_commands.gd
│   │   └── android_commands.gd
│   ├── services/                  # Runtime autoload services
│   │   ├── mcp_runtime_bridge.gd  # In-game scene tree / properties / script execution
│   │   ├── mcp_input_bridge.gd    # Input event queue
│   │   └── mcp_screenshot_bridge.gd
│   └── utils/
│       ├── type_parser.gd         # Vector2 / Color type parsing
│       ├── node_utils.gd
│       └── resource_utils.gd
├── server/                        # Node.js MCP server
│   ├── src/
│   │   ├── index.ts               # MCP stdio entry
│   │   ├── godot-bridge.ts        # WebSocket server + JSON-RPC
│   │   ├── tools.ts               # Tool registration
│   │   └── tool-manifest.ts       # 173 tool definitions (name / description / params)
│   └── build/index.js             # Build output (MCP entry point)
├── example/                       # Demo Godot project
├── .mcp.json.example              # Sample MCP client config
├── README.md                      # English docs (default)
└── README.zh.md                   # Chinese docs

Requirements

• Godot 4.4+
• Node.js 18+
• Any MCP-capable client: Claude Code, Cursor, Codex CLI, Cline, Windsurf, etc.

Usage

1. Install the Godot plugin

Copy addons/godot_mcp/ into your Godot project's addons/ directory:

cp -r addons/godot_mcp /path/to/your-game/addons/

Enable it in Godot: Project → Project Settings → Plugins → Godot MCP → Enable

Enabling the plugin injects 3 autoloads (MCPRuntimeBridge, etc.); they are removed when the plugin is disabled.

2. Build the MCP server

cd server
npm install
npm run build

The entry point after build is server/build/index.js.

3. Configure your AI client

Add the following to your MCP config file (replace paths with your actual paths):

{
  "mcpServers": {
    "godot-mcp": {
      "command": "node",
      "args": ["D:/godot-mcp/server/build/index.js"],
      "env": {
        "GODOT_MCP_PORT": "6505"
      }
    }
  }
}

See also .mcp.json.example in the repo.

4. Get started

1. First, open your project in Godot (with the plugin enabled)
2. Start your AI client and confirm the godot-mcp MCP server is connected
3. Ask the AI to operate the editor, for example:
   • "Get the current scene tree"
   • "Add a CharacterBody2D named Player under the root"
   • "Create a GDScript and attach it to Player"
   • "Play the current scene, then capture a game screenshot"
   • "Fill a grass area on the TileMap"

5. Example project

The example/ directory contains a runnable demo project:

godot --editor example/project.godot

How it works

1. The AI client calls an MCP tool (e.g. add_node) over stdio
2. The Node.js server converts the request to JSON-RPC and sends it over WebSocket to the Godot plugin
3. The plugin's command_router dispatches to the matching handler, which calls EditorInterface and related APIs
4. The result travels back to the AI client along the same path

Runtime tools (e.g. get_game_scene_tree) additionally require:

• The editor to be in Play mode
• The MCPRuntimeBridge autoload polling user://mcp_runtime_req.json in the game process and writing responses

Adding a tool

To add a new MCP tool:

1. Create or edit a command class under addons/godot_mcp/commands/ and register the handler in get_commands()
2. Add the script path to the COMMAND_MODULES array in command_router.gd
3. Add the tool name, description, and parameter schema to TOOL_DEFINITIONS in server/src/tool-manifest.ts

Then rebuild the server:

cd server && npm run build

Known limitations

• Android tools: list_android_devices runs adb devices; deploy_to_android uses headless Godot export and adb install (requires an Android export preset and adb on PATH)
• Runtime tools: call play_scene first; the game process must load the MCPRuntimeBridge autoload; watch_signals listens for signal emissions on specified nodes while the game is running
• Cross-scene batch edits (cross_scene_set_property): modifies scene instances in memory — save the affected scene files manually
• Some editor APIs may differ across Godot minor versions; 4.4+ is recommended

License

MIT