godot-mcp

A Godot 4.7 editor plugin that serves the open editor as an MCP server, so Claude Code (or any MCP client) can read and change the live project: scenes, nodes, scripts (GDScript and C#), project settings, asset imports, headless runs and .NET builds. Node edits go through the editor's undo history.

The addon in addons/godot_mcp/ is the product. It serves Streamable HTTP at http://127.0.0.1:<port>/mcp and needs nothing else installed.

Requirements

• Godot 4.7 (the .NET build for the C# tools: create_dotnet_project, build_dotnet, .cs scripts)

• Linux or macOS (the generated Claude Code entry uses a POSIX shell headersHelper)

• Claude Code with HTTP MCP servers

Related MCP server: Godot Universal MCP

Install the addon

From your Godot project's root, take the latest version from the default branch:

curl -fsSL https://github.com/voidrot/godot-mcp/archive/HEAD.tar.gz \
  | tar -xz --strip-components=1 --wildcards '*/addons/godot_mcp/*'

This replaces addons/godot_mcp/. Run it again to update. Then enable Godot MCP under Project > Project Settings > Plugins. On first load the addon picks a port between 6550 and 6649, saves it as godot_mcp/server/port, and writes an access token to .godot/godot_mcp/headers.json (inside .godot/, so it stays out of version control).

Connect Claude Code

In the editor, run Project > Tools > MCP: install agent skill / show config. It installs the agent skill into .claude/skills/godot-mcp/ and shows the .mcp.json entry to paste into the project's .mcp.json:

{
  "mcpServers": {
    "godot-editor": {
      "type": "http",
      "url": "http://127.0.0.1:6550/mcp",
      "headersHelper": "cat '/abs/path/to/project/.godot/godot_mcp/headers.json'"
    }
  }
}

Use the port your project shows. Accept the trust dialog when Claude Code starts, then claude mcp list should show godot-editor connected. The editor must be running for the tools to respond.

Tools

Project: get_project_info, get_project_settings, set_project_setting, install_agent_skill. Scenes and nodes: get_scene_tree, open_scene, create_scene, save_scene, add_node, delete_node, move_node, get_node_properties, update_property. Scripts: read_script, create_script, edit_script, validate_script. Jobs: run_headless, import_assets, build_dotnet, create_dotnet_project. Editor: get_editor_log, play_scene, stop_scene. addons/godot_mcp/SKILL.md documents each one, its values, errors and limits.

Development

bun install
bun run check

check runs Biome, the TypeScript check and the tests, which drive a real godot-mono --headless --editor. The Bun stdio server in src/ is the earlier v0 and is kept only as a test and conformance harness. Plans and design decisions are in docs/plans/.

License

MIT