G-MCP: Model Context Protocol Server for Godot 4.x

G-MCP is a Model Context Protocol (MCP) server that integrates directly with the Godot 4.x Engine, empowering AI coding agents (like Claude Desktop, Cursor, or custom agents) with unparalleled capabilities for runtime debugging, visual game inspections, automated playtesting, input emulation, and workspace management.

With G-MCP, an AI agent can build features, inspect live scenes, execute GDScript expressions on a running game, take screenshots to visually confirm layouts, dispatch keyboard/mouse input, and debug errors dynamically in real-time.

🚀 Key Features & Capabilities

• 🧠 Runtime Debugging & Introspection: Inspect the running scene tree, read or modify live node properties, invoke methods, connect or disconnect signals, serialize state, and monitor performance.
• 🎮 Input Emulation & Automated Playtesting: Synthesize keyboard, mouse, gamepad, and touch events (including scroll and drag) or run scripted input sequences. Use this to drive gameplay automation and testing.
• ⚡ Dynamic GDScript Execution (eval): Write and run arbitrary GDScript snippets on the running game instance dynamically, and retrieve the returned results.
• 📸 Visual Agent Vision: Capture screenshots of the running game window, the Godot editor, or the full desktop monitor, returning base64 images directly to your agent's vision pipeline.
• 🛠️ Scene & Resource Editing: Create/read scene files (.tscn), add/remove/rename/reparent nodes, instance PackedScenes, update node groups, and query the Godot ClassDB API.
• 📂 Filesystem & Workspace Mapping: Map project directories, read/edit scripts, validate script syntax, and rescan the Godot filesystem from the server.
• 🌐 Web Asset Integration: Search and download game assets directly from Kenney.nl, OpenGameArt, itch.io, and auto-extract ZIP archives into your project.

🏗️ Architecture & Dual-Execution Modes

G-MCP operates as a hybrid server to provide maximum reliability, whether the game is actively running, open in the editor, or closed:

graph TD
    Agent[AI Agent / MCP Client] -->|Stdio| Server[G-MCP Server]
    
    subgraph Live Mode (Connected)
        Server -->|WebSocket port 6505| Editor[Godot Editor Plugin]
        Server -->|WebSocket port 6505| Runtime[Game Session Autoload]
        Editor -->|Bridge| Runtime
    end
    
    subgraph Headless Fallback Mode
        Server -->|Godot CLI Executable| Headless[Headless GDScript Runner]
    end

1. Live/Active Mode (WebSocket Bridge): When the Godot Editor is open with the G-MCP plugin enabled, or the game is running, the server connects over a local WebSocket (port 6505). This allows the agent to communicate instantly with the editor and live game session (required for runtime debugging, screen capture, and input dispatch).
2. Headless Fallback Mode (CLI execution): If the editor is closed, the server automatically falls back to invoking Godot in headless CLI mode (--headless) using the included gesso_headless_runner.gd script. Filesystem, scene-tree generation, and resource tools still work seamlessly.

📋 Compatibility & Requirements

• Godot Engine: Godot 4.0 - 4.3+ (Core compatibility optimized for Godot 4.x).
• MCP Clients: Fully compatible with Claude Desktop, Cursor, VS Code, and any system supporting the Model Context Protocol.
• Runtime Environments: Node.js v18 or later.
• Operating Systems: Windows (Powershell/Cmd), macOS, and Linux.

🛠️ Installation & Setup

You can set up G-MCP automatically using our interactive configuration wizard, or perform a manual setup.

🚀 Option 1: One-Command Automated Setup (Recommended)

The easiest way to install the Godot addon and configure your coding agent is to use the interactive setup wizard.

1. If using G-MCP globally from NPM: Run the following command in your terminal:

   npx g-mcp-server setup

   For faster offline agent startup, install globally first and run the setup wizard from that stable install:

   npm install -g g-mcp-server
   g-mcp-server setup

2. If you cloned the G-MCP repository locally: Run these commands inside your local gesso-mcp-server directory:

   npm install
   npm run build
   npm run setup:agent

💡 Important Notes During Setup:

• Godot Project Path: When the wizard asks you to “Enter absolute path to your Godot project,” you must specify the exact folder on your hard drive where your project.godot file resides (e.g., C:/Users/username/Documents/MyGodotGame).
• Automated Addon Copying: The setup wizard will automatically create the addons/godot_mcp folder inside your Godot project and copy the G-MCP Editor Addon and Autoload script directly into it.
• Agent Integration: The wizard will write or merge the required configuration into your preferred coding agent (Claude Desktop, Cursor, Windsurf, Cline, or Continue).
• Cursor Tool Limit: Cursor exposes roughly 40 MCP tools at once, so the wizard installs the small g-mcp-router plus one direct g-mcp-workspace server. Use the router's call_godot_mcp_tool for everything else.

🔄 Working on a Different Project?

If you decide to switch and work on a different Godot game project:

• For Cursor (Project-level): Cursor loads settings from your project folder's .cursor/mcp.json. Run the setup command again, select your new project, and select Cursor. This writes a new config file and installs the addon inside your new project folder. Cursor will automatically use it when you open that project.
• For other agents: Claude Desktop, Windsurf, Cline, and Continue use user-level or workspace-level config files. You must run the setup command again (or edit your agent's config manually) to update GODOT_MCP_PROJECT_ROOT to point to your new project's path.

🎮 Enable the Plugin in Godot

Once the setup wizard has finished copying the files:

1. Open your project in the Godot 4.x Editor.
2. Go to Project > Project Settings > Plugins.
3. Locate Gesso MCP (or G-MCP) and check the Enable box. (This automatically registers the MCPRuntime autoload pointing to res://addons/godot_mcp/runtime/gesso_runtime.gd in your project settings).

📝 Option 2: Manual Installation (Advanced)

If you prefer to configure G-MCP manually:

1. Build the Server

Clone the repository and compile the TypeScript:

cd g-mcp
npm install
npm run build

2. Copy files to Godot

1. Copy the src/scripts/gesso_editor_addon folder to your Godot project's addons/ directory and rename it to godot_mcp.
2. Copy src/scripts/gesso_runtime_autoload.gd to res://addons/godot_mcp/runtime/gesso_runtime.gd.
3. Enable the plugin under Project Settings > Plugins in the Godot Editor.

3. Manually Configure the MCP Client

Add G-MCP to your agent's configuration file:

• Claude Desktop (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

  {
    "mcpServers": {
      "g-mcp-server": {
        "command": "node",
        "args": ["C:/path/to/gesso-mcp-server/dist/index.js"],
        "env": {
          "GODOT_MCP_PROJECT_ROOT": "C:/path/to/your/godot-project-directory-containing-project-godot",
          "GODOT_MCP_GODOT_PATH": "C:/path/to/Godot_v4.x_console.exe",
          "GODOT_MCP_PORT": "6505",
          "GODOT_MCP_LOG_LEVEL": "warn"
        }
      }
    }
  }

🧰 Complete Tool Catalog

The G-MCP Server registers the following tools with the client:

1. Runtime Debugging & Control

These tools inspect and control the game while it is running. Most of these require play mode (run_scene with wait_for_runtime=true first).

| Tool Name | Description | | :--- | :--- | | run_scene | Launches a scene in the editor (optionally blocking until MCPRuntime connects). | | stop_scene | Stops the currently running scene. | | get_runtime_status| Status snapshot of the editor play state and MCPRuntime connection. | | is_playing | Compatibility shim checking if a scene is currently running. | | query_runtime_node| Read class details, groups, and properties (e.g. position, visibility) of a live Node. | | get_runtime_log | Read runtime logs from the game's internal MCPRuntime ring buffer. | | capture_screen | Captures a PNG of the game, editor, or desktop for agent vision (base64). | | take_screenshot | Saves a PNG screenshot from the active game viewport. | | send_input | Synthesizes an InputEvent (keys, mouse buttons, motion) in the active game. | | test_input_sequence| Runs a scripted sequence of inputs (clicks, keys, mouse drags, waits). | | wait | Sleeps the server-side thread to pause between inputs. |

2. Scene & Node Editing

Create, inspect, and modify scenes and their nodes.

| Tool Name | Description | | :--- | :--- | | create_scene | Generates a new .tscn file with a root node. | | read_scene | Parses a .tscn file and dumps its hierarchy, node types, and properties. | | add_node | Adds a child node (supporting basic types or PackedScene instances). | | remove_node | Deletes a node from a scene. | | rename_node | Renames a node. | | move_node | Re-orders or reparents a node within the scene tree. | | modify_node_property| Modifies a single node property inside a .tscn file. | | set_node_properties| Modifies multiple node properties at once. | | attach_script | Attaches a .gd script to a node. | | detach_script | Detaches a script from a node. | | set_collision_shape| Sets collision bounds (Circle, Rectangle, Capsule) on a CollisionObject. | | set_sprite_texture| Assigns a texture file to a Sprite2D or TextureRect. | | instance_scene | Instances a PackedScene inside another scene. | | set_mesh | Sets a mesh on a MeshInstance3D. | | set_material | Assigns a Material to a mesh. | | get_node_spatial_info| Reads transforms (position, rotation, scale) for 2D/3D nodes. | | measure_node_distance| Measures spatial distance between two nodes. | | snap_node_to_grid| Snaps a node position to a grid increment. | | get_node_groups | Returns a node's group memberships. | | set_node_groups | Configures the group list for a node. | | find_nodes_in_group| Locates all nodes registered to a specific group. |

3. Resource & Signal Routing

Manipulate resources and connect event signals.

| Tool Name | Description | | :--- | :--- | | get_resource_info | Dumps details (properties, types, scripts) from a resource (.tres, .res). | | set_resource_property| Modifies a property on a resource. | | save_resource_to_file| Saves a resource to disk. | | list_signal_connections| Lists connections (signals, targets, flags) for a Node. | | connect_signal | Connects a signal to a method on another Node. | | disconnect_signal| Breaks a signal connection. |

4. Project & Settings Management

Configure project parameters and query metadata.

| Tool Name | Description | | :--- | :--- | | get_project_settings| Concise summary of project settings (scenes, window sizes, physics). | | list_settings | Browse and filter settings from ProjectSettings. | | update_project_settings| Sets settings (values, graphics, etc.) inside project.godot. | | get_input_map | Returns defined input actions and their key/axis mappings. | | configure_input_map| Adds, removes, or modifies input actions and mappings.| | get_collision_layers| Returns the 2D/3D physics collision layer names. | | list_viewport_presets| Lists common 2D PC indie resolution presets. | | configure_game_viewport| Configures standard viewport sizing, scaling, and window properties. | | classdb_query | Explores class hierarchy, methods, and properties from Godot's ClassDB. | | rescan_filesystem| Tells the editor to rescan directory changes. | | setup_autoload | Adds, removes, or lists autoload singletons. | | map_project | Builds a complete architectural map of script references and scenes. |

5. File & Asset Tools

Basic directory navigation and asset acquisition.

| Tool Name | Description | | :--- | :--- | | list_dir | Lists directories and files inside res://. | | read_file | Reads lines of a file (highly optimized node-based). | | create_folder | Creates directories recursively. | | delete_file | Deletes a file (with optional backup). | | rename_file | Renames or moves a file. | | search_assets | Queries OpenGameArt, Kenney, itch.io, and PolyHaven for assets. | | inspect_asset_page| Scrapes asset downloads and licenses from a URL. | | download_asset | Downloads an asset URL and optionally auto-extracts ZIP archives. |

6. Script Editing & Visualizer

Validate scripts and access visualizer hooks.

| Tool Name | Description | | :--- | :--- | | create_script | Generates a new script file with boilerplate code. | | edit_script | Performs regex modifications on script files. | | list_scripts | Lists all .gd script files in the project. | | validate_script | Validates syntax of a GDScript file. | | open_in_godot | Opens a file in the Godot Editor. | | scene_tree_dump | Dumps the scene tree of the active editor tab. | | get_console_log | Retrieves lines from the Godot editor output log. | | get_errors | Retrieves errors/warnings from the debugger output. | | clear_console_log| Marks a cursor in the output log to ignore older prints. | | generate_2d_asset| Utility hook for asset generation pipelines. |

🔍 Troubleshooting

WebSocket Port Conflicts (EADDRINUSE)

If you start the MCP server and receive a port conflict warning:

• The server automatically detects stale processes from previous sessions on port 6505 (on Windows) and attempts to release them.
• If a conflict persists, verify that no other game or editor session is running on port 6505.
• You can change the bridge port by setting the GODOT_MCP_PORT environment variable in your client configuration, and adding --mcp-port=[PORT] to your Godot command line arguments.

Godot Executable Not Found

If headless tools fail with an error indicating Godot cannot be found:

• Ensure Godot is added to your environment PATH.
• Alternatively, set the GODOT_MCP_GODOT_PATH environment variable in your MCP configuration to point directly to your Godot 4 console executable (e.g. C:\Program Files\Godot\Godot_v4.3-stable_win64_console.exe). Legacy GODOT_PATH is still supported.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.