AI-godot-mcp

中文文档

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

Inspired by dpeachpeach/godot-mcp

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

Installation

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

Enable Plugin

In Godot Editor:

1. Open your project
2. Navigate to Project → Project Settings → Plugins
3. Enable "AI Godot MCP"

Configure MCP Client

Claude Code

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

Restart Claude Code and the tools will be available.

<details> <summary><strong>Other MCP Clients</strong></summary>

For any MCP-compatible client, use this configuration:

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

</details>

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

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.

Building from Source

<details> <summary>Expand to view</summary>

git clone https://github.com/DC925928496/AI-godot-mcp.git
cd AI-godot-mcp
npm install
npm run build

Then point your MCP client configuration to build/index.js instead of using npx.

</details>

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