AI-godot-mcp

[中文文档](docs/README_zh.md)

Production-grade Godot MCP service for AI-driven game development.

Inspired by dpeachpeach/godot-mcp

Vision

AI-godot-mcp aims to let ordinary people build Godot games with coding agents such as Codex, using this project as the editor bridge and the Godot editor as the live development surface.

The long-term goal is not to hard-code game-building workflows into MCP. The goal is to give agents a reliable Godot execution layer: the agent does the planning and reasoning, while AI-godot-mcp safely inspects, mutates, runs, and observes the editor on the agent's behalf.

What Comes Next

The repository already has the low-level MCP bridge. The next direction is to make that bridge a better execution substrate for Codex-style agents:

• keep workflow intelligence in the agent layer, while expanding MCP into a more complete and composable Godot capability surface
• strengthen the observe-repair loop with clearer in-editor status, operation history, and run feedback
• lower the onboarding cost with starter templates, example projects, and docs that show how agents can drive the editor effectively
• expand the Godot authoring surface toward signals, input maps, scene instancing, autoloads, and common UI flows

Features

🔍 Project Inspection

• `get_project_context` - Retrieve Godot version, project name, and plugin status
• `get_scene_tree` - Get current scene node tree (supports depth limit and type filtering)
• `get_editor_logs` - Fetch editor output panel logs (supports timestamp and level filtering)

🎨 Scene Editing

• `create_scene` - Create new scene files
• `add_node` - Add nodes to scene tree with automatic parent resolution
• `set_node_property` - Modify node properties with type validation
• `delete_node` - Delete nodes with full undo support
• `load_resource` - Load and reference external resources
• `save_current_scene` - Save current scene to disk

⚡ Transaction Management

• `begin_ai_action` / `end_ai_action` - Atomic batch operations with native UndoRedo integration

📝 Script Management

• `attach_script` - Attach GDScript to nodes with automatic template generation
• `get_resource_uid` - Get resource UID for cross-reference validation

▶️ Scene Execution

• `play_current_scene` - Run current scene in editor (F6)
• `stop_running_scene` - Stop running scene (F8)

🛠️ CLI Tools

• `install` - Deploy plugin to Godot projects with version validation
• `uninstall` - Clean removal of plugin from projects
• `version` - Display version and compatibility information

Requirements

• Godot: 4.6.x only
• Node.js: ≥20.0.0

Quick Start

Choose one MCP server startup method, then load the Godot editor plugin for the project you want the agent to operate on.

Option 1: npx

npx ai-godot-mcp install "<godot-project-path>"

Use this when you want npm to download and run the published package on demand. The MCP client starts the stdio server with npx ai-godot-mcp.

#### Claude Code

claude mcp add ai-godot-mcp -- npx ai-godot-mcp

#### Other MCP Clients

Use this server configuration:

{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "npx",
      "args": ["ai-godot-mcp"]
    }
  }
}

Option 2: GitHub Releases

Use this when you downloaded the packaged release artifact instead of pulling from npm at runtime.

npm install -g "./ai-godot-mcp-<version>.tgz"
ai-godot-mcp install "<godot-project-path>"

Then point your MCP client at the installed command:

claude mcp add ai-godot-mcp -- ai-godot-mcp

{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "ai-godot-mcp",
      "args": []
    }
  }
}

If a release also provides plugin-only.zip, that file only installs the Godot addon manually. It does not start the Node MCP server; use one of the server startup methods above or below.

Option 3: Build from Source

Use this when developing the project locally or testing unpublished changes.

git clone https://github.com/DC925928496/AI-godot-mcp.git
cd AI-godot-mcp
npm install
npm run build
node build/cli/index.js install "<godot-project-path>"

Then point your MCP client to the built server entrypoint:

claude mcp add ai-godot-mcp -- node "E:/code/AI-godot-mcp/build/index.js"

{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "node",
      "args": ["E:/code/AI-godot-mcp/build/index.js"]
    }
  }
}

Re-run npm run build after changing TypeScript source.

Load the Godot Plugin

After installing or copying the addon:

1. Open exactly one target Godot project.
2. Navigate to Project → Project Settings → Plugins.
3. Enable "AI Godot MCP".
4. Restart or reload your MCP client so it discovers the server tools.

Only one Godot project should load the plugin at a time. The plugin listens on local port 6550; if two editors load it, one editor may fail to bind the port or the MCP server may connect to the wrong project. Before switching projects, disable the plugin or close the current Godot editor, then enable it in the next project.

Architecture

AI-godot-mcp uses a WebSocket communication architecture:

• Node MCP Server (WebSocket client) ↔ Godot Editor Plugin (WebSocket server on port 6550)
• All write operations integrate with Godot's native UndoRedo system, supporting atomic transactions
• Unified response format: {ok: true, data} or {ok: false, error: {code, message, suggestions}}

CLI Commands

MCP server

npx ai-godot-mcp

Starts the MCP server over stdio. MCP clients usually run this command for you. For a release package installed globally, use ai-godot-mcp. For a source checkout, use node build/index.js after npm run build.

install

npx ai-godot-mcp install "<project-path>"

Deploy plugin to Godot project with version compatibility validation (Godot 4.6.x only).

uninstall

npx ai-godot-mcp uninstall "<project-path>"

Remove addons/ai_godot_mcp/ directory from project.

version

npx ai-godot-mcp version

Display version information and supported Godot versions.

Troubleshooting

• Godot version mismatch → Ensure you're using Godot 4.6.x (verify with godot --version)
• Plugin not enabled → Check Project → Project Settings → Plugins in editor, ensure "AI Godot MCP" is checked
• WebSocket connection failed → Confirm plugin is started and port 6550 is not occupied
• Tool call timeout → Ensure Godot editor is running and plugin is loaded

License

MIT