Use with an AI client

godot-mcp serve gives an MCP client the same complete workflow as the CLI: discover the live engine, build in the open editor, run and play the game, observe state, debug failures, fix them, and verify the result. It runs as a Model Context Protocol server over stdio. Clients that speak streamable HTTP can skip the binary and connect straight to the editor, which hosts its own MCP endpoint.

Two tool modes#

By default, serve exposes every command as a first-class MCP tool with a real JSON schema: a tool name like node_add, typed parameters with required flags, and a one-line description. The schemas are built live from the addon’s own param docs on the first tools/list and cached, so the tool surface can never drift from what the editor actually registers (including any project-local commands). Alongside the typed tools sits godot_run, the generic escape hatch: give it { "method": "<group>.<command>", "params": {…} } and it proxies any method to the addon.

For clients that cap the number of tools, run serve --typed=false to expose only godot_run. One tool still reaches all 330 registered commands while keeping the model’s context lean: the model discovers the live 4.7 API with engine.search / engine.class_info, then acts, instead of carrying every tool schema into the session. Both modes are deliberate: typed for schema-guided calls, single-tool for context economy.

Write the config automatically#

godot-mcp configure writes an MCP-server entry for a supported client, merging without clobbering your other servers:

godot-mcp configure claude --project /path/to/your/project
godot-mcp configure cursor
godot-mcp configure vscode
godot-mcp configure codex --global

Add --print to emit the snippet without writing (the safe path for uncertain global targets).

--project must name a real Godot project, meaning the directory holding project.godot or anywhere inside it. Configure refuses a directory that is in no project: the config it would write leaves the server unable to resolve a project root, so it falls back to port 9080 and skips the check that the answering editor is the right one.

When the Godot project sits in a subdirectory of a larger repo, --config-dir puts the config where the client reads it while the server still drives the project:

godot-mcp configure claude --project ./game --config-dir .

Or configure by hand#

{
  "mcpServers": {
    "godot-mcp": {
      "command": "godot-mcp",
      "args": ["serve", "--project", "/path/to/your/project"]
    }
  }
}

The Godot editor must be open with the plugin enabled, exactly as for the CLI. --project sets where the server discovers the addon port, so it survives an editor restart.

Or connect straight to the editor (streamable HTTP)#

The addon hosts a streamable-HTTP MCP endpoint inside the editor at POST /mcp on 127.0.0.1, so an MCP client that speaks streamable HTTP connects with no external process at all:

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://127.0.0.1:9100/mcp"
    }
  }
}

The endpoint picks the first free port in 9100-9115 and records it as http_port in <project>/.godot/godot-mcp.json; pin a fixed one with the godot_mcp/network/http_port project setting (Project → Project Settings → Godot Mcp) or the GODOT_MCP_HTTP_PORT environment variable.

The tool surface mirrors serve: the generic godot_run plus every documented command as a typed tool, dispatched through the same command router with the same safety guards. Two settings tune it:

The endpoint listens on loopback and checks the Origin header, so a web page you happen to have open cannot reach it: requests carrying no Origin (every native MCP client) or an origin whose host is localhost, ::1, or a loopback address are served, anything else gets 403, and the CORS header echoes the allowed origin rather than *. A browser-based MCP client running on http://localhost:<port> works unchanged. The WebSocket transport cannot be gated the same way. The threat model covers what that does and does not mean.

Read-only resources#

Beyond the tools, the server advertises read-only MCP resources under the godot:// scheme, so a client can pull context without spending a tool turn:

Prompts#

serve also ships the durable playbooks as first-class MCP prompts, so a client can pull them with prompts/get, even when the editor is down: