Godot MCP

中文文档

Model Context Protocol server for Godot Engine — 279 tools, 26 categories, Godot 4.6/4.7 coverage. File-based CRUD + live editor plugin. AI assistants read, inspect, and modify Godot projects through stdio transport.

Table of Contents

• Quick Start
• Feature Overview
• Installation
• AI Client Configuration
• Usage Examples
• Editor Plugin
• Architecture
• Supported Formats
• Development
• VSIX Packaging

Quick Start

# Option 1: npx (no install, available after npm publish)
npx -y @yanhuifair/godot-mcp -p /path/to/your/godot/project

# Option 2: global install
npm install -g @yanhuifair/godot-mcp
godot-mcp -p /path/to/your/godot/project

The AI client launches the MCP server automatically — no manual run needed. Just configure and start chatting:

"List all scenes in the project" "Find all CharacterBody2D nodes" "Run the game and take a screenshot"

Feature Overview

Total: 279 tools across 26 categories

Installation

npx (recommended, no pre-install)

npx -y @yanhuifair/godot-mcp -p /path/to/your/godot/project

Global Install

npm install -g @yanhuifair/godot-mcp

From Source

git clone https://github.com/yanhuifair/Godot-MCP.git
cd godot-mcp
npm install
npm run build

Environment Variables

Godot auto-detection: GODOT_PATH → /Applications/Godot.app → PATH → snap/flatpak

AI Client Configuration

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
    }
  }
}

Or with a global install:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "godot-mcp",
      "args": ["-p", "/path/to/your/godot/project"]
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "/path/to/your/godot/project"]
    }
  }
}

Local Development

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/index.js", "-p", "/path/to/your/godot/project"]
    }
  }
}

Usage Examples

Browse Project

"Show me the project structure"
→ list_project_files → full file tree

"Generate a project overview report"
→ generate_project_report → scenes/scripts/shaders/resources stats

"Check project health"
→ validate_project → broken refs, missing UIDs

Create Resources

"Create a 2D platformer scene"
→ create_scene → scenes/main.tscn

"Create a metallic material"
→ create_resource → materials/metal.tres
→ set_material_param → metallic=0.9, roughness=0.3

Search & Locate

"Find all Timer nodes"
→ find_nodes_in_scenes → cross-scene search with paths

"Search for _ready functions"
→ search_in_scripts → matches with function context

"List all UI buttons in the project"
→ list_ui_nodes → anchors, positions, text

Run & Debug

"Run the game at 1280x720 and take a screenshot"
→ run_project → launches game
→ capture_screenshot → gameplay.png

"Stop the running game"
→ stop_project → terminates all Godot processes

Script Operations

"Analyze player.gd structure"
→ read_script_structure → class name, signals, exports, functions

"Add a dash method to Player"
→ add_script_function → safe method injection

"Validate all scripts"
→ validate_script → per-file syntax/logic check

Animation Editing

"Show player animations"
→ read_animation → track list + keyframes

"Add a position track to idle animation"
→ add_animation_track → track_path=".:position"

"Set a keyframe at 0.5s"
→ set_keyframe → time=0.5, value="Vector2(100,0)"

Audio Setup

"Show audio bus layout"
→ read_audio_bus_layout → bus hierarchy, volumes, effects

"Add reverb to Master"
→ add_bus_effect → effect_type="Reverb"

"Set SFX bus volume"
→ set_bus_volume → bus_index=2, volume_db=-6.0

Scene Editing

"Add a Timer under Player"
→ add_node → type=Timer, name=Cooldown

"Clone Enemy node as Enemy2"
→ clone_node → clone_source="Main/Enemy", name="Enemy2"

"Connect body_entered signal"
→ connect_signal → from_node="Player", signal="body_entered", method="_on_body_entered"

Editor Plugin

The optional editor plugin provides real-time editor control via TCP on port 9876 — select nodes, play/stop, undo/redo, save, breakpoints, debugging, and more.

Install the Plugin

1. Copy the plugin to your project:

cp -r addons/godot_mcp /path/to/your/godot/project/addons/

1. Enable in Godot: Project → Project Settings → Plugins → Godot MCP → Enable

1. If not visible, click Restart or reopen the project

1. Confirm in the Output panel:

[Godot MCP] TCP server listening on port 9876

Editor Tools (78 tools)

View & Selection: editor_get_selection editor_set_selection editor_get_open_scene editor_read_current_scene editor_get_info editor_get_rect editor_focus editor_show_in_filesystem editor_open_dock

Playback Control: editor_play editor_stop editor_run_specific_scene editor_get_running_scene_tree editor_get_performance

Edit Operations: editor_undo editor_redo editor_save editor_save_all editor_reload_scene editor_delete_selected

Scene Operations: editor_create_scene editor_instantiate_scene editor_set_main_scene editor_get_scene_changes

Node Operations: editor_add_node editor_remove_node editor_duplicate_node editor_rename_node editor_reparent_node editor_move_node editor_get_node_properties editor_set_node_properties

Scripting: editor_create_script editor_attach_script editor_run_gdscript editor_evaluate_expression

Debugging: editor_set_breakpoint editor_remove_breakpoint editor_get_breakpoints editor_debug_continue editor_debug_step editor_debug_step_over editor_debug_break editor_get_stack_trace editor_get_debug_variables

Signals: editor_connect_signal editor_disconnect_signal editor_list_node_signals

File System: editor_open_asset editor_list_filesystem editor_create_folder editor_delete_asset editor_rename_asset editor_move_asset editor_duplicate_asset editor_reimport_asset editor_get_dependencies

Project Settings: editor_get_project_setting editor_set_project_setting editor_get_editor_setting editor_set_editor_setting editor_get_project_directory

Input & Autoloads: editor_get_input_map editor_add_input_action editor_remove_input_action editor_get_autoloads editor_add_autoload editor_remove_autoload

Assets: editor_bake_lightmaps editor_bake_navigation editor_take_screenshot

Class Documentation: editor_get_class_list editor_get_method_list editor_get_class_properties editor_get_class_signals editor_get_class_doc editor_search_help

Camera & Viewport: editor_get_camera editor_set_camera editor_toggle_grid editor_toggle_snap

Other: editor_get_recent_scenes editor_simulate_key editor_get_plugin_list editor_enable_plugin editor_disable_plugin editor_get_errors editor_clear_errors editor_health_check

Architecture

┌─────────────────────┐
│   AI Client          │
│ (Cursor/Claude/Copilot)│
└────────┬────────────┘
         │ MCP (stdio)
┌────────▼──────────────┐        TCP :9876      ┌──────────────────┐
│   Godot MCP Server     │ ◄───────────────────► │  Godot Editor     │
│   (TypeScript, 279 tools)│   (editor plugin)   │  (GDScript addon) │
│                        │                       │                  │
│  ┌──────────────────┐  │                       │  78 editor cmds   │
│  │  Tool Handlers    │  │                       │  JSON-RPC/TCP    │
│  └──────────────────┘  │                       └──────────────────┘
│  ┌──────────────────┐  │
│  │  File Parsers     │  │  .tscn / .tres / .gd / .gdshader / .import / .csv
│  └──────────────────┘  │
│  ┌──────────────────┐  │
│  │  Godot CLI        │  │  Launch, run, export, screenshot
│  └──────────────────┘  │
└────────────────────────┘

Project Structure

godot-mcp/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server.ts             # MCP server core
│   ├── tools/                # 33 handler files
│   │   ├── register.ts       # Centralized registration (279 tools)
│   │   ├── project.ts        # Project tools
│   │   ├── scene.ts          # Scene tools
│   │   ├── script.ts         # Script + shader tools
│   │   ├── editor.ts         # Live editor tools
│   │   ├── resource.ts       # Resource/material/theme
│   │   ├── godot.ts          # Engine control
│   │   ├── animation.ts      # Animation pipeline
│   │   ├── audio.ts          # Audio bus
│   │   ├── environment.ts    # Environment resources
│   │   ├── physics.ts        # Physics materials
│   │   ├── import.ts         # Import config
│   │   ├── inspector.ts      # Node inspectors
│   │   ├── shader_graph.ts   # VisualShader graph
│   │   ├── tileset.ts        # TileMap/TileSet
│   │   ├── navigation.ts     # Navigation mesh
│   │   ├── translation.ts    # Translation files
│   │   ├── diff.ts           # File comparison
│   │   ├── texture.ts        # Texture info
│   │   ├── extension.ts      # GDExtension/C#
│   │   ├── uid.ts            # File UIDs
│   │   ├── joint.ts          # Physics joints
│   │   ├── geometry.ts       # 2D geometry shapes
│   │   ├── rendering.ts      # Mesh/Viewport/RayCast
│   │   ├── domain.ts         # Curve/Gradient/Skeleton/Path
│   │   ├── nodes.ts          # Node-specific inspectors
│   │   ├── utility.ts        # Utilities
│   │   └── coverage.ts       # Mesh/2D lights/vehicles etc.
│   ├── parsers/
│   │   ├── scene_parser.ts   # .tscn parser
│   │   ├── resource_parser.ts # .tres parser
│   │   ├── config_parser.ts  # project.godot parser
│   │   └── parser_helpers.ts # Shared parsing utilities
│   └── utils/
│       ├── types.ts          # Type definitions
│       ├── file_utils.ts     # File system operations
│       ├── godot_cli.ts      # Godot CLI interface
│       ├── registry.ts       # Tool registry
│       ├── errors.ts         # Error codes
│       └── cache.ts          # File cache
├── addons/
│   └── godot_mcp/            # Godot editor plugin
│       ├── plugin.cfg         # Plugin metadata
│       └── plugin.gd          # TCP server + command handlers
├── dist/                     # Compiled output
├── test/                     # Test suite
├── package.json
└── README.md

Supported Formats

Development

npm install              # Install dependencies
npm run build            # Build TypeScript → dist/
npm run dev              # Dev mode (tsx hot reload)
npm test                 # Run 138 tests
npm run test:watch       # Watch mode

CLI Options

Tech Stack

• Runtime: Node.js ≥18
• Language: TypeScript 5.5
• MCP SDK: @modelcontextprotocol/sdk ^1.29
• Schema: Zod ^3.24
• Test: Vitest ^2.0
• Transport: stdio

VSIX Packaging

npm run vsix
# → godot-mcp-1.0.0.vsix

Install in VS Code:

code --install-extension godot-mcp-1.0.0.vsix

After installation, the MCP server auto-registers. Copilot / Cline / Roo Code discover it automatically — no manual mcp.json config required.

Limitations

• Binary .res files not supported — use .tres (text format)
• Godot CLI tools require the Godot Engine binary
• Screenshots depend on OS-native tools
• edit_scene uses AST manipulation on .tscn; complex refactors may need manual verification

License

MIT