godot-mcp

An MCP server for the Godot 4 engine. It lets AI agents such as Claude Code, Claude Desktop, Cursor, VS Code Copilot, Codex, Gemini CLI, Windsurf and Zed work on your Godot project:

• inspect and edit scenes, nodes, signals and resources
• author animations, AnimationTrees, SpriteFrames, tile maps, navigation, audio buses and visual shaders
• change project settings, input actions, autoloads, import options and export presets, and run exports
• write scripts with GDScript language-server diagnostics, symbols and renames
• look up the Godot class reference offline for the exact version you have installed
• run the game and work on it live: inspect and change nodes, send input, pause and step frames, take screenshots, profile, record and replay input
• debug with breakpoints, stepping, stack and variables, and run GUT or GdUnit4 tests

It works through a live editor bridge, so every scene edit can be undone with Ctrl+Z, and through headless Godot when the editor is closed.

Requirements

• Godot 4.7 or newer (tested with 4.7.2)
• Node.js 22 or newer, unless you use the Claude Desktop bundle, which brings its own

Install

In your Godot project folder (the one with project.godot), run:

npx -y @shin2344234/godot-mcp init

init shows its plan and asks before writing anything (--dry-run previews, --remove undoes). It copies the editor addon into addons/godot_mcp and enables it, registers the server with the agents it finds on your machine (or the ones you pick with --agents claude-code,cursor,vscode,codex,gemini-cli,...), and adds a short note to AGENTS.md.

Then open the project in Godot, start a new agent session and ask it to call godot_status to check the connection.

Other ways to install

• Claude Code plugin: run /plugin marketplace add shin2344234/godot-mcp, then /plugin install godot-mcp@godot-mcp.

• Claude Desktop: download the .mcpb file from Releases and double-click it.

• Any other MCP client: add the server to its config by hand. docs/setup.md gives the exact file and format for each client.

• From source:

  git clone https://github.com/shin2344234/godot-mcp
  cd godot-mcp/server && npm install && npm run build
  cd /path/to/my-game
  node /path/to/godot-mcp/server/dist/index.js init
  

If you installed without init, ask the agent to run godot_addon_install once per project to add the editor addon.

Documentation

• Setup for each client: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Windsurf and Zed, all options, and Windows notes
• Tools: every tool by group, tool modes and toolsets, resources and prompts
• How it works: editor bridge, headless fallback, the in-game runtime, safety and context size
• Troubleshooting: error messages and fixes
• All documentation, including the per-area method references and protocol designs
• Changelog · Contributing · Security

License

MIT