Godot MCP Native (Model Context Protocol)

中文版本

A powerful Godot Engine plugin that integrates AI assistants (Claude, etc.) via the Model Context Protocol (MCP). Enable AI to directly read and modify your Godot projects - scenes, scripts, nodes, and resources - all through natural language.

🚀 Features

• Full Project Access: AI assistants can read and modify scripts, scenes, nodes, and resources
• Native Implementation: No Node.js dependency required - runs entirely within Godot
• Real-time Editing: Apply AI suggestions directly in the editor
• Comprehensive Tool Set (155 tools — 30 core + 125 supplementary):
  • Node Tools (9 core + 11 advanced): Create, modify, manage scene nodes, duplicate, move, rename, signal connections, anchor presets, group management, batch operations, scene auditing
  • Script Tools (7 core + 8 advanced): Edit, analyze, create, attach, validate GDScript and C# files, execute scripts, search in files, symbol indexing, definition & reference lookup
  • Scene Tools (4 core + 4 advanced): Manipulate scene structure, save scenes, list/open/close scene tabs, project scene listing
  • Editor Tools (4 core + 12 advanced): Control editor functionality, screenshot, signal inspection, filesystem reload, node/file selection, export management, property inspector
  • Debug Tools (3 core + 68 advanced): Logging, debugger sessions, breakpoints, stack/variable inspection, profilers, runtime probe, animation/audio/shader/tilemap runtime control, debug execution control, await_scene_ready
  • Project Tools (3 core + 23 advanced): Access project settings, list resources, create resources, run tests, manage input mappings, inspect autoloads/global classes, resource diagnostics & health audit

📦 Installation

Method 1: Asset Library (Recommended)

1. Open your Godot project
2. Go to AssetLib tab in the editor
3. Search for "Godot MCP Native"
4. Click Download and then Install

Method 2: Manual Installation

1. Download or clone this repository
2. Copy the addons/godot_mcp folder to your project's addons/ directory
3. Open your project in Godot
4. Go to Project > Project Settings > Plugins
5. Enable "Godot MCP Native" plugin

🔧 Usage

Enabling the Plugin

1. Open Project > Project Settings > Plugins
2. Locate "Godot MCP Native" in the list
3. Set the status to Enable

Configuring MCP Server

The plugin provides two transport modes:

• Best for: Network-based AI integration
• Configuration: Set transport_mode = "http" and configure http_port (default: 9080)
• Optional: Enable auth_enabled and set auth_token for security

Launch the editor in headless MCP-server mode:

godot --editor --path /path/to/project -- --mcp-server

Settings changed in the panel persist to user://mcp_settings.cfg. Headless --mcp-server mode honors this file, so the http_port / transport_mode / auth options configured via the editor UI are respected when running headlessly.

To run multiple instances in parallel (several projects, or isolated test instances), override the port per launch with command-line flags — the command line takes precedence over the persisted config:

godot --editor --path /path/to/projectA -- --mcp-server --mcp-port=9080
godot --editor --path /path/to/projectB -- --mcp-server --mcp-port=19081

Connecting with Claude Desktop

First, install the mcp-remote package:

npm install mcp-remote

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9080/mcp"
      ]
    }
  }
}

Connecting with Cursor / Trae

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://localhost:9080/mcp"
    }
  }
}

With authentication:

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://localhost:9080/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token-here"
      }
    }
  }
}

Connecting with Cline

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://localhost:9080/mcp",
      "type": "streamableHttp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Connecting with OpenCode

{
  "mcp": {
    "godot-mcp": {
      "type": "remote",
      "url": "http://localhost:9080/mcp"
    }
  }
}

Connecting with Codex

[mcp_servers]

[mcp_servers.godot-mcp]
type = "streamableHttp"
url = "http://localhost:9080/mcp"

💬 Example Prompts

Once connected, you can interact with your Godot project through Claude:

@mcp godot-mcp read godot://script/current

I need help optimizing my player movement code. Can you suggest improvements?

@mcp godot-mcp get-scene-tree

Add a cube in the middle of the scene and create a camera that looks at it.

Create a main menu with Play, Options, and Quit buttons

Implement a day/night cycle system with dynamic lighting

📚 Available Commands

Node-Write (6)

• create-node - Create a new node
• delete-node - Delete a node
• update-node-property - Update node properties
• duplicate-node - Duplicate a node and its children
• move-node - Move a node to a new parent
• rename-node - Rename a node in the scene

Node-Read (3)

• get-scene-tree - Get scene tree structure
• get-node-properties - Get properties of a specific node
• list-nodes - List nodes under a parent

Node-Write-Advanced (5)

• set-anchor-preset - Set anchor preset for Control nodes
• connect-signal - Connect a signal between nodes
• disconnect-signal - Disconnect a signal connection
• set-node-groups - Set group memberships for a node
• add-resource - Add a resource child node (collision shape, mesh, etc.)

Node-Advanced (6)

• get-node-groups - Get groups a node belongs to
• find-nodes-in-group - Find all nodes in a specific group
• batch-update-node-properties - Batch update multiple node properties in one UndoRedo action
• batch-scene-node-edits - Apply batch scene node create/delete/move edits in one UndoRedo action
• audit-scene-node-persistence - Audit node owner and persistence state for the scene
• audit-scene-inheritance - Audit inherited/instanced scene structure

Script (7)

• list-project-scripts - List all scripts
• read-script - Read a specific script
• modify-script - Update script content
• create-script - Create a new script
• get-current-script - Get currently editing script
• attach-script - Attach an existing script to a node
• execute-script - Execute GDScript expression

Script-Advanced (8)

• analyze-script - Analyze script structure
• validate-script - Validate GDScript syntax
• search-in-files - Search project files
• list-project-script-symbols - Index script symbols across GDScript and C# files
• find-script-symbol-definition - Find definition locations for a script symbol
• find-script-symbol-references - Find textual references to a script symbol
• rename-script-symbol - Rename a script symbol across project files
• open-script-at-line - Open a script at a specific line in the editor

Scene (4)

• create-scene - Create a new scene
• save-scene - Save current scene
• open-scene - Open a scene
• get-current-scene - Get current scene info

Scene-Advanced (4)

• list-project-scenes - List all scenes
• get-scene-structure - Get scene structure details
• list-open-scenes - List currently open scene tabs
• close-scene-tab - Close a scene tab

Editor (4)

• get-editor-state - Get current editor state
• run-project - Run the project
• stop-project - Stop the running project
• execute-editor-script - Execute GDScript script

Editor-Advanced (12)

• get-selected-nodes - Get selected nodes
• set-editor-setting - Modify editor settings
• get-editor-screenshot - Capture an editor viewport screenshot
• get-signals - Inspect node signals and connections
• reload-project - Rescan the project filesystem
• select-node - Select a node in the scene and focus in Inspector
• select-file - Select a file in the FileSystem dock
• get-inspector-properties - Inspect node/resource properties like the Inspector
• list-export-presets - List export presets
• inspect-export-templates - Inspect installed export templates
• validate-export-preset - Validate an export preset
• run-export - Run a Godot CLI export

Debug (3 core + 68 advanced)

• get-editor-logs - Get editor/runtime logs
• debug-print - Print debug info
• clear-output - Clear MCP/editor output buffers
• get-performance-metrics - Get performance data
• get-debugger-sessions - List editor debugger sessions and active/break state
• set-debugger-breakpoint - Enable or disable debugger breakpoints
• send-debugger-message - Send custom messages to the running game debugger
• toggle-debugger-profiler - Toggle EngineProfiler channels in active sessions
• get-debugger-messages - Read custom runtime messages captured by the bridge
• add-debugger-capture-prefix - Capture additional EngineDebugger message prefixes
• get-debug-stack-frames - Read captured script stack frames from a breaked session
• get-debug-stack-variables - Read locals, members, and globals for a captured stack frame
• install-runtime-probe - Add the MCP runtime probe node to the current scene
• remove-runtime-probe - Remove the MCP runtime probe node from the current scene
• request-debug-break - Ask the runtime probe to enter Godot's debug break loop
• send-debug-command - Send step/next/out/continue/stack debugger commands to breaked sessions
• get-runtime-info - Query runtime metrics (FPS, node count, etc.) through the probe
• await-scene-ready - Wait until a specific scene is loaded through the probe
• get-runtime-scene-tree - Read the live runtime scene tree from the running game
• inspect-runtime-node - Inspect a live runtime node and its serializable properties
• update-runtime-node-property - Modify a property on a live runtime node
• call-runtime-node-method - Call a method on a live runtime node
• evaluate-runtime-expression - Evaluate a GDScript expression in the running game
• await-runtime-condition - Poll a runtime expression until truthy or timeout
• assert-runtime-condition - Assert a runtime expression becomes truthy within timeout
• get-debug-threads - Return DAP-style debugger threads
• get-debug-state-events - Read recorded debugger state transitions
• get-debug-output - Read categorized runtime debugger output
• get-debug-scopes - Group stack variables into DAP-like scopes
• get-debug-variables - Resolve DAP-style variable references
• expand-debug-variable - Expand a debug variable by scope and path
• evaluate-debug-expression - Evaluate an expression in debugger context
• debug-step-into / debug-step-over / debug-step-out / debug-continue - Debug execution control
• debug-step-into-and-wait / debug-step-over-and-wait / debug-step-out-and-wait / debug-continue-and-wait - Debug execution with state wait
• await-debugger-state - Check debugger session execution state
• get-runtime-performance-snapshot - Capture runtime performance snapshot
• get-runtime-memory-trend - Capture runtime memory trend
• create-runtime-node - Create a node in the running game
• delete-runtime-node - Delete a node from the running game
• simulate-runtime-input-event - Inject structured InputEvent
• simulate-runtime-input-action - Inject InputEventAction
• list-runtime-input-actions - List runtime InputMap actions
• upsert-runtime-input-action - Create/update a runtime InputMap action
• remove-runtime-input-action - Remove a runtime InputMap action
• list-runtime-animations - List animations on a runtime AnimationPlayer
• play-runtime-animation - Play a runtime animation
• stop-runtime-animation - Stop a runtime animation
• get-runtime-animation-state - Get runtime animation playback state
• get-runtime-animation-tree-state - Get runtime AnimationTree state
• set-runtime-animation-tree-active - Enable/disable runtime AnimationTree
• travel-runtime-animation-tree - Travel runtime animation state machine
• get-runtime-material-state - Resolve runtime node material binding
• get-runtime-theme-item - Resolve runtime Control theme item
• set-runtime-theme-override - Apply runtime theme override
• clear-runtime-theme-override - Remove runtime theme override
• get-runtime-shader-parameters - List runtime shader parameters
• set-runtime-shader-parameter - Update runtime shader uniform
• list-runtime-tilemap-layers - List runtime TileMap layers
• get-runtime-tilemap-cell - Get runtime TileMap cell data
• set-runtime-tilemap-cell - Write/erase runtime TileMap cell
• list-runtime-audio-buses - List runtime audio buses
• get-runtime-audio-bus - Get runtime audio bus state
• update-runtime-audio-bus - Update runtime audio bus
• get-runtime-screenshot - Capture runtime viewport screenshot

Project (3 core + 23 advanced)

• get-project-info - Get project information
• get-project-settings - Get project settings
• list-project-resources - List project resources
• create-resource - Create a new resource
• get-project-structure - Get project directory structure
• list-project-tests - Discover and list runnable project tests
• run-project-test - Run a single project test
• run-project-tests - Run multiple project tests
• list-project-input-actions - List project InputMap actions
• upsert-project-input-action - Create or update a project InputMap action
• remove-project-input-action - Remove a project InputMap action
• list-project-autoloads - List project autoload entries
• list-project-global-classes - List project global script classes
• get-class-api-metadata - Get ClassDB or global class API metadata
• inspect-csharp-project-support - Inspect C# project support files
• compare-render-screenshots - Compare two screenshots for pixel differences
• inspect-tileset-resource - Inspect a TileSet resource
• reimport-resources - Reimport resources through the import pipeline
• get-import-metadata - Get resource import metadata
• get-resource-uid-info - Inspect ResourceUID mappings
• fix-resource-uid - Ensure a resource has a persisted UID
• get-resource-dependencies - List resource dependencies
• scan-missing-resource-dependencies - Find broken dependency references
• scan-cyclic-resource-dependencies - Find cyclic dependency chains
• detect-broken-scripts - Scan scripts for syntax errors
• audit-project-health - Run a project health audit

🔒 Security Recommendations

• ✅ Production: Always enable authentication (auth_enabled = true)
• ✅ Token: Use a strong token (≥16 characters with letters, numbers, special characters)
• ✅ Storage: Don't commit tokens to version control
• ⚠️ Remote Access: Use HTTPS (TLS/SSL) for network access

📋 Requirements

• Godot Engine 4.x (recommended 4.5 or higher)
• No additional dependencies (native implementation)

📖 Documentation

For detailed documentation, see the docs/current/ folder:

• Quick Start Guide
• Architecture Design
• Tools Reference
• Testing Guide

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

yurineko73

🙏 Acknowledgments

• Godot Engine team for the amazing game engine
• Model Context Protocol (MCP) specification
• Claude AI by Anthropic for inspiring this integration

Note: This is a community plugin and is not officially affiliated with Godot Engine or Anthropic.