godot-mcp

godot-mcp is a Godot 4.7 editor addon. It runs an MCP server inside the editor, so Claude Code or another MCP client works on the project that is open in front of you. Claude can read and change the live scene tree, scripts and project settings, import assets, and run the game headless or build a .NET project. Node edits go through the editor's undo history, so you can undo them like any other edit.

What you can ask Claude to do

• "Add a Sprite2D under Player, set its texture to res://art/player.png, and save the scene."

• "Write a script for Enemy that moves toward the player, attach it, and check that it parses."

• "Run the main scene headless and tell me about any errors it prints."

• "Show me the editor log from the last run."

• "Set the physics ticks per second to 120 in project settings."

• "This project has no C# yet. Create the .NET project, add a Player.cs script, and build it."

Related MCP server: Godot Universal MCP

Requirements

• Godot 4.7. The test suite runs against Godot 4.7.2 (mono build).

• For C#: the .NET (mono) build of Godot, and dotnet on your PATH. build_dotnet runs dotnet build, and create_dotnet_project creates the project files.

• A program named timeout on your PATH for run_headless and build_dotnet, which run in a separate process. (import_assets runs inside the editor and does not need it.) The addon looks for that exact name, so it must be GNU timeout. Without it those two fail with SPAWN_FAILED.

• Linux or macOS. Setup refuses Windows, because the .mcp.json entry it writes uses a POSIX shell command. macOS does not ship GNU timeout. Install GNU coreutils, and make its unprefixed timeout (for Homebrew, the gnubin directory of the coreutils install) visible to the editor. A gtimeout name is not enough.

• Claude Code with HTTP MCP server support, or another MCP client that supports Streamable HTTP and custom headers.

Install the addon

From your Godot project's root, run:

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

This downloads the latest version from the default branch and writes it into addons/godot_mcp/. Files with the same names are overwritten.

GNU tar (Linux) needs --wildcards. macOS's bsdtar rejects that flag, so on macOS leave it out:

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

Then enable the plugin: Project > Project Settings > Plugins, and turn on Godot MCP. On first load the addon picks the first free port from 6550 to 6649 on 127.0.0.1 and saves it as godot_mcp/server/port in project.godot. It reuses that port from then on. Each time the plugin loads, it:

• Writes a new access token to .godot/godot_mcp/headers.json. The folder gets a .gitignore that ignores everything in it, so the token stays out of version control.

• Prints godot_mcp: serving http://127.0.0.1:<port>/mcp in the editor's Output panel.

To update, run the install command again, then reload the plugin or restart the editor. Run the setup menu item again (see Connect Claude Code, step 1) so the agent skill matches the new version.

Connect Claude Code

1. Open the project in the editor and choose Project > Tools > MCP: install agent skill / show config. The dialog writes the agent skill to .claude/skills/godot-mcp/SKILL.md and shows the MCP entry. The Copy button copies it. Setup never writes .mcp.json for you.

2. Paste the entry into .mcp.json at the project root, creating the file if it does not exist. It looks like this, with the port your project uses:

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

   The headersHelper reads the current token from headers.json each time the client connects, so you never copy the token by hand.

3. Start Claude Code in the project and approve the godot-editor server when it asks. Then run:

   claude mcp list

   godot-editor should be listed as connected. If it is not, approve the server when Claude Code asks, then check again. The editor must be running for the tools to respond.

Other MCP clients

Any client that speaks Streamable HTTP and can send a custom header can connect. Use:

• URL: http://127.0.0.1:<port>/mcp

• Header: Authorization: Bearer <token>, where the token is the value in .godot/godot_mcp/headers.json

The server accepts protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. It answers with plain JSON and keeps no session between requests.

Tools

Every tool is listed with its arguments and errors in addons/godot_mcp/SKILL.md, which the setup step copies into your project.

Project

• get_project_info: Project name, main scene, features, autoloads, the root .csproj, open and unsaved scenes, and whether a job is running (jobActive).

• get_project_settings: Read settings with their defaults.

• set_project_setting: Write a setting to project.godot. Settings under editor/, editor_plugins/ and godot_mcp/ are refused.

• install_agent_skill: Write the agent skill into the project and return the .mcp.json entry.

• create_dotnet_project: Create the root .csproj and .sln for a Godot .NET project.

Scenes and nodes

• get_scene_tree: List the edited scene's nodes.

• open_scene: Make a .tscn or .scn the edited scene.

• create_scene: Create a new .tscn with a root node of a given class, and open it.

• save_scene: Write the edited scene to its file.

• add_node: Add a node of a class, or an instance of a scene.

• delete_node: Delete a node and its children.

• move_node: Move a node under a new parent, or reorder it.

• get_node_properties: Read a node's editor-visible properties.

• update_property: Set one editor-visible property as one undoable action. property can also be script (attaches a script) or name (renames the node), and rotation_degrees sets the rotation in degrees.

Scripts

• read_script: Read a .gd or .cs file.

• create_script: Create a .gd or .cs file.

• edit_script: Replace one exact snippet, or the whole file, in a .gd or .cs file.

• validate_script: Check a .gd file for parse errors.

Running and building

• run_headless: Run the project, a scene or a script in a separate headless process, and return its output.

• import_assets: Rescan the project and import new or changed assets.

• build_dotnet: Build the project's .csproj with dotnet build.

• play_scene: Play a scene in the editor. Output is not captured.

• stop_scene: Stop the scene that is playing.

• get_editor_log: Read the editor's errors, warnings and printed output.

How changes land

• Node edits change the open scene in the editor. Each one is a single undo step. They reach disk when Claude calls save_scene.

• create_scene, script writes, and set_project_setting write files immediately.

• run_headless reads files on disk, not the editor's state. Save the scene first, or the run uses the old content. Its result includes unsavedScenes when the editor has unsaved scenes.

Troubleshooting

Security

The server listens only on 127.0.0.1, so other machines on your network cannot reach it. Every request must carry the bearer token from .godot/godot_mcp/headers.json. The token is 32 random bytes, and the plugin makes it owner-readable only.

The token is the only access control, and it is not a sandbox. Anything that can read the token can change your project and run its code. Some tools run project code directly: run_headless and play_scene run the game, build_dotnet runs MSBuild targets and analyzers, and @tool scripts run when the editor loads them. Use this server only with projects you trust, and only with clients you trust on your machine.

The script tools refuse to write or validate files under addons/godot_mcp/ (PROTECTED_PATH). This guards against mistakes, not against a hostile client.

Development

bun install
bun run check

check runs Biome, the TypeScript check, and the tests. The editor tests start a real godot-mono --headless --editor with the addon enabled. Set GODOT_BIN to use another binary. The Bun stdio server in src/ is an earlier version kept as a test and conformance harness. Plans and design decisions are in docs/plans/.

License

MIT. See LICENSE.