Godot MCP

The most complete MCP server for Godot Engine — 386 tools that give your AI assistant real hands inside your game project.

English | 中文文档

Godot MCP is a Model Context Protocol server that connects any AI assistant — Claude, Cursor, VS Code Copilot, Windsurf, Cline, Codex, Aider — directly to Godot Engine 4.x. Your AI stops guessing about your project and starts operating it.

• 📂 Reads and writes your project files natively — .tscn scenes, .tres resources, GDScript, C#, .gdshader, project.godot. Custom parsers, no Godot process required, instant response.
• 🎛️ Drives the live editor — select nodes, connect signals, author visual shaders, bake lightmaps, set breakpoints, step the debugger, run and stop the game.
• ↩️ Every scene edit is undoable — add, remove, rename, move, reparent, duplicate and instantiate all register on Godot's native undo stack. If the AI gets it wrong, Ctrl+Z puts it back.
• 🎮 Reaches inside the running game — inspect the live scene tree, call methods, inject input, freeze the game, step it one frame at a time, and screenshot the result. No other public Godot MCP does this.
• 🔎 Stays usable at scale — search_tools finds the right tool out of 386, get_status tells you exactly what is connected, and every error returns a typed code plus a repair hint.

386 tools · 30 categories · 22 AI clients · 4 communication paths · one-command setup.

npx @yanhuifair/godot-mcp --enable-plugin -p .

| Requirement | | |---|---| | Godot | 4.x (Godot 3 not supported) | | Node.js | >= 18 | | AI Client | Any MCP-compatible client (see Configuration) |

Why Godot MCP

| | Godot MCP | Other Godot MCP servers | |---|---|---| | Tool count | 386 across 30 categories | 16 – 156 | | Works without Godot running | ✅ Native .tscn / .tres / .godot parsers | ⚠️ Usually needs a live editor | | Live editor control | ✅ 140 tools — play, debug, breakpoints, viewport, bake | Partial | | Undoable AI edits | ✅ Every scene mutation is one Ctrl+Z away — native EditorUndoRedoManager actions | ❌ Edits are permanent | | Control the running game | ✅ 11 tools — live tree, method calls, input injection | ❌ None | | Deterministic frame stepping | ✅ runtime_freeze → runtime_step → runtime_screenshot | ❌ None | | Tool discovery for large catalogs | ✅ search_tools + get_status | ❌ None | | Error messages | ✅ Typed error code + actionable repair hint | Raw stack traces | | Transports | Stdio · SSE · Streamable HTTP | Usually stdio only | | Editor plugin install | ✅ One command, auto-enabled | Manual copy | | Engine introspection | ✅ Live ClassDB — classes, methods, properties, signals, docs | Rare |

If you have ever wanted to say "run the game, freeze it at the moment the player lands, and show me the collision state" — this is the server that can actually do it.

Table of Contents

1. Why Godot MCP
2. Quick Start
3. What You Can Do
4. Architecture
5. Implementation Principles
6. Transport Modes
7. Installation
8. AI Client Configuration
9. Usage Examples
10. Editor Plugin
11. Tool Discovery & Live Game Runtime
12. All Tools
13. Supported Formats
14. Development
15. Build VSIX

Quick Start

Two setup steps, about two minutes. You do not need to install anything globally, and you do not need to keep a terminal open — your AI client starts the server for you.

Before You Begin

| You need | How to check | |---|---| | Godot 4.x installed | Open Godot → the version shows in the title bar. (Godot 3 is not supported.) | | Node.js 18 or newer | Run node -v in a terminal. If it says command not found, install from nodejs.org. | | An MCP-capable AI client | VS Code + Copilot, Cursor, Claude Desktop, Windsurf, Cline… see the full list. |

Step 1 — Install the Editor Plugin

Open a terminal, cd into your Godot project folder (the one containing project.godot), and run:

npx @yanhuifair/godot-mcp --enable-plugin -p .

Run this from your project root — the folder containing project.godot — because -p . means "the current directory". If you run it from anywhere else, pass an absolute path instead: npx @yanhuifair/godot-mcp --enable-plugin -p /Users/me/games/my-game

Always installs the latest version. npx fetches the newest release every time. To force it or pin a specific version: npx @yanhuifair/godot-mcp@latest --enable-plugin -p . (latest) · npx @yanhuifair/[email protected] --enable-plugin -p . (pinned)

What this does: copies the plugin into addons/godot-mcp/ and switches it on inside project.godot. Nothing to click in Godot.

How to confirm it worked: you should now see an addons/godot-mcp/ folder in your project. If Godot is already open, reload the project (Project → Reload Current Project) so it picks up the plugin.

Only if you want the live editor and live game tools (play the scene, read the current selection, set breakpoints, bake lightmaps, freeze the running game…).

Over 220 of the 386 tools — everything that reads and writes .tscn, .tres, .gd, shaders, project settings, etc. — work without the plugin and without Godot even being open. If that's all you need, skip to Step 2.

Step 2 — Point Your AI Client at the Server

Create .vscode/mcp.json in your project root (this exact file works for VS Code / GitHub Copilot):

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

Then restart your AI client so it reads the new config.

Using something else? The config file has a different name and location per client, but the command / args part is almost always identical. Copy-paste blocks for Cursor, Claude Desktop, Claude CLI, Windsurf, OpenAI Codex, Cline, Roo Code, Continue, Aider, Cody, Goose, Zed are in AI Client Configuration.

Step 3 — Verify and Start Chatting

Ask your AI:

"Run get_status"

You should get back the tool count and whether the editor / runtime bridges are reachable. That means everything is wired up. Now try:

"List all scenes in the project"
"Find all CharacterBody2D nodes and tell me their collision layers"
"Run the game and take a screenshot"

With 386 tools, the AI can't see them all at once — tell it to search_tools when it isn't sure what's available (e.g. "search_tools for animation").

| Symptom | Fix | |---|---| | Client shows no godot-mcp tools | Restart the client. Config files are only read on startup. | | npx: command not found | Node.js isn't installed or isn't on your PATH. Run node -v to confirm. | | Project not found errors | The -p path must point at the folder containing project.godot. Using "." only works if the client's working directory is your project — otherwise use an absolute path. | | Editor tools fail, file tools work | The plugin isn't installed/enabled. Re-run Step 1, then reload the project in Godot. | | EDITOR_NOT_REACHABLE | Godot isn't running, or the plugin isn't enabled. The server will try to launch Godot itself; if that fails, open the project in Godot manually and check Project → Project Settings → Plugins → Godot MCP is enabled. | | EDITOR_COMMAND_FAILED | The editor received the command but refused it — usually a wrong node path, a property that doesn't exist on that node type, or an invalid target. The message carries Godot's own reason. Use editor_get_scene_tree / get_class_properties to verify before retrying. | | AI made a scene edit you don't want | Press Ctrl+Z in Godot, or call editor_undo. Every MCP scene mutation is a native undo action. | | Godot binary not found | Set the GODOT_PATH environment variable to your Godot executable. See Environment Variables. |

What You Can Do

Godot MCP provides comprehensive coverage of the Godot 4.x engine through 386 tools in 30 categories.

Quick Demo

# One command to set up everything
npx @yanhuifair/godot-mcp --enable-plugin -p .

# Then ask your AI:
> "Create a 2D platformer scene with a CharacterBody2D player"
> "Add a Timer node, connect its timeout signal, write the handler"
> "Create a metallic PBR material and apply it to all MeshInstance3D nodes"
> "Set up an audio bus with reverb, set SFX volume to -6dB"
> "Set a breakpoint at line 42, run the game, step through the debugger"

Feature Overview

| Category | Tools | Description | |---|---|---| | Editor | 140 | Live editor control — select, play, undo, save, breakpoints, file ops, performance | | Project | 24 | Config, input map, file ops, autoloads, export presets, validation, unused assets | | Scene | 22 | Scene CRUD — nodes, signals, transforms, collision, sprites | | Script + Shader | 21 | GDScript/Shader CRUD, structure analysis, code injection, validation | | Domain | 14 | Curve, Gradient, Path, Skeleton, ReflectionProbe, MultiMesh, NoiseTexture | | Animation | 10 | AnimationPlayer/AnimationTree — tracks, keyframes, parameters | | Godot Engine | 9 | Engine detection, launch editor, run/export project, screenshot | | Coverage | 18 | Mesh primitives, 2D lights, vehicles, spring arm, decal, occluder, grid map | | Node Inspectors | 8 | CharacterBody, AnimatedSprite, Audio, Video, Parallax, RichText, Container, Tab | | Resource | 8 | .tres CRUD, PBR materials, themes, 14 templates | | Audio | 7 | Audio bus layout, effects, volume | | Shader Graph | 8 | VisualShader graph — 40+ node types, connections, parameters | | Utility | 9 | Signal catalog, StyleBox, AtlasTexture, popup listing, cohesion report | | Rendering | 5 | MeshInstance, Viewport, Area, RayCast/ShapeCast | | Environment | 6 | Environment read/write, presets | | Inspector | 5 | Camera, Light, Particle node inspection | | Physics | 5 | PhysicsMaterial CRUD, collision layers | | Import | 3 | .import file read/write | | TileMap | 5 | TileSet resources, TileMapLayer inspection | | Navigation | 6 | NavigationRegion, NavigationMesh | | Translation | 8 | CSV/PO translation files, .po authoring, registration | | Joints | 5 | Physics joints — create, configure, list | | UID | 4 | File UID query, batch update, missing UID detection | | 2D Geometry | 4 | CollisionPolygon2D, shape point editing | | Diff | 5 | Scene and resource comparison | | Texture | 4 | Texture import/read/write, atlas, noise | | Extension/World/C# | 5 | GDExtension, C#, World3D, CSProj | | Meta / Introspection | 2 | Tool search (search_tools) + system diagnostics (get_status) | | Logs | 5 | Read game-run logs (user://logs/godot.log), list/rotate, clear, locate user-data dir, configure file logging | | Runtime (game) | 11 | Control the running game — tree, properties, methods, signals, input, freeze/step, screenshot |

Total: 386 tools across 30 categories

Core Capabilities in Detail

Project Management Read and write project.godot settings, input maps, autoload singletons, and export presets. Perform file operations (list, search, move, delete with .bak backups), validate project health, detect unused assets, and generate comprehensive project reports.

Scene Editing Full CRUD on .tscn scene files. Add, delete, modify, clone, and rename nodes. Edit node properties, transforms (position/rotation/scale), collision shapes, and sprite textures. Connect and disconnect signals between nodes. Search nodes across scenes by type, property, group, or signal.

Scripting & Shaders Read, write, and create GDScript, C#, and .gdshader files. Analyze script structure (class names, signals, exported variables, functions). Inject functions, signals, and @export variables into existing scripts. Validate GDScript for common syntax issues. Validate and compile shaders. Manage VisualShader graphs — add, remove, connect, and configure nodes.

Resource Management Read, write, and create .tres resource files with 14 built-in templates (StandardMaterial3D, ShaderMaterial, ORMMaterial3D, CanvasItemMaterial, and more). Inspect and modify PBR material parameters. Read Theme resources with properties grouped by type.

Animation Pipeline Complete AnimationPlayer and AnimationTree support: list animations, read tracks and keyframes, create new animations, add/remove tracks, set keyframes at specific times, configure animation libraries, and inspect AnimationTree state machines.

Audio Configuration Read, create, and modify audio bus layouts. Add and remove audio buses, attach effects (14 types: Reverb, Delay, Chorus, Compressor, and more), and set bus volume in dB.

Physics & Collision Inspect VehicleBody3D, SoftBody3D, and physics materials. Create collision shapes. Read collision layer and mask configuration from project settings. Create physics joints (PinJoint, HingeJoint, SliderJoint, and more).

Rendering & Environment Inspect MeshInstance3D, Viewport, Area, and RayCast nodes. Create and configure Environment resources (4 presets). Manage 2D lights, decals, and occluders. Read 3D mesh primitives (Box, Sphere, Capsule, Cylinder, Torus, and more).

Live Editor Control (140 tools) Interact with the running Godot editor in real time over a TCP or stdio bridge: select nodes, run/stop/pause the project, undo/redo, save scenes, create and attach scripts, set breakpoints, step the debugger, evaluate expressions, control the 3D viewport camera, bake lightmaps and navigation meshes, manage plugins, and simulate key presses.

Live Game Runtime Control (11 tools) Go beyond the editor and reach into the actually running game. Inspect the live scene tree with real positions, read and write node properties at runtime, call arbitrary methods, emit signals, inject keyboard input, and — the headline feature — runtime_freeze the game, runtime_step forward an exact number of frames, and runtime_screenshot the result. This makes AI-driven gameplay debugging deterministic and reproducible.

Visual Shader Graphs Create and modify VisualShader graphs programmatically. Add nodes from a catalog of 40+ types (constants, math operations, textures, inputs), connect node ports, set node parameters, and list available node types with their default input/output configurations.

Engine Introspection (ClassDB) Query the live engine's ClassDB: list all classes, inspect methods, properties, and signals of any Godot type, read built-in class documentation, and search the help system. The AI works from ground truth instead of hallucinating APIs.

TileMap, Navigation & Translation Inspect TileSet resources and TileMapLayer nodes. List and read NavigationRegion nodes, create NavigationMesh resources. Read and create CSV/PO translation files with search support.

Architecture

System Overview

                        MCP Protocol (stdio/SSE/Streamable HTTP)
  +-----------------+                                        +------------------+
  |   AI Client      |<-------------------------------------->|  Godot MCP Server |
  |  (VS Code/Cursor |                                        |  (TypeScript)     |
  |   Claude/etc.)   |                                        |                  |
  +-----------------+                                        |  +-------------+ |
                                                             |  | Tool Registry| |
                                                             |  |  (386 tools) | |
                                                             |  +------+------+ |
                                                             |         |        |
                                                             |    +----v-----+  |
                        File I/O (direct)                    |    | Parsers   |  |
  +------------------+<-------------------------------------->|    | .tscn     |  |
  |   Godot Project   |                                       |    | .tres     |  |
  |   Files on Disk   |                                       |    | .godot    |  |
  |  (.tscn/.tres/.gd)|                                       |    +----------+  |
  +------------------+                                       |                  |
                                                             |  +-------------+ |
                        stdin/stdout (spawned process)       |  | Godot CLI   | |
  +------------------+<-------------------------------------->|  | (spawn/edit) | |
  |   Godot Editor    |                                       |  +-------------+ |
  |  (GDScript addon) |                                       +------------------+
  |  TCP port 9876    |
  |  102 commands     |
  +------------------+

Communication Paths

The server uses four distinct communication paths depending on the operation:

1. Direct File I/O — For file-based tools (read_scene, write_script, create_resource, etc.), the server reads and writes Godot project files directly on disk using custom parsers. No Godot process is required. This is the fastest path.

2. Godot CLI — For engine operations (launch_editor, run_project, export_project, get_godot_version), the server spawns Godot as a subprocess and communicates via command-line arguments and stdout/stderr.

3. Editor Bridge (dual-mode) — For live editor tools (editor_get_selection, editor_play, editor_set_breakpoint, etc.), the MCP server communicates with a running Godot editor instance. Two modes are supported:

   • TCP mode (default): Connects to an already-running Godot on localhost:9876. The editor plugin listens on this port.
   • Stdio mode (fallback): Spawns Godot as a child process with --editor --path <project>, sets MCP_STDIO=true, and communicates via stdin/stdout using JSON-RPC with a __MCP__: marker prefix. This mode auto-starts and auto-restarts Godot as needed.

4. Live-Game Runtime Bridge — For runtime tools (runtime_*, e.g. runtime_get_tree, runtime_set_node, runtime_step), the MCP server talks to a small autoload running inside your played game on 127.0.0.1:9877. The autoload (addons/godot-mcp/runtime_bridge.gd, named godot_mcp_runtime) is added to your project and listens only on loopback. This lets the AI inspect and mutate the live scene tree, inject input, pause/resume, deterministically step frames, and screenshot the running game — a tier no other public Godot MCP offers out of the box.

Project Structure

godot-mcp/
├── src/
│   ├── index.ts              # CLI entry point, argument parsing, transport dispatch
│   ├── server.ts             # MCP server factory, tool registration, request routing
│   ├── tools/                # tool handler files (one group per category)
│   │   ├── register.ts       # Centralized registration (386 tools)
│   │   ├── project.ts        # Project management tools
│   │   ├── scene.ts          # Scene editing tools
│   │   ├── script.ts         # Script and shader tools
│   │   ├── editor.ts         # Live editor bridge (TCP + stdio, persistent connection)
│   │   ├── resource.ts       # Resource/material/theme tools
│   │   ├── godot.ts          # Godot engine control
│   │   ├── animation.ts      # Animation pipeline
│   │   ├── audio.ts          # Audio bus management
│   │   ├── scene_inspectors.ts  # 2D lights, vehicles, spring arm, etc.
│   │   ├── mesh.ts           # 3D mesh primitives
│   │   ├── shader_graph.ts   # VisualShader graph editing
│   │   └── ... (16 more files: domain, physics, navigation, joints, etc.)
│   ├── parsers/
│   │   ├── scene_parser.ts   # .tscn file parser (sections, nodes, connections)
│   │   ├── resource_parser.ts # .tres file parser
│   │   ├── config_parser.ts  # project.godot INI parser
│   │   └── parser_helpers.ts # Shared utilities (quote handling, bracket balancing)
│   ├── transports/
│   │   ├── stdio.ts          # Stdio transport (default, for local AI clients)
│   │   └── http-server.ts    # SSE + Streamable HTTP transport
│   └── utils/
│       ├── types.ts          # TypeScript type definitions
│       ├── file_utils.ts     # File system operations with path traversal protection
│       ├── godot_cli.ts      # Godot binary detection, process management
│       ├── registry.ts       # ToolRegistry class with sorted listing
│       ├── errors.ts         # Structured error codes
│       └── cache.ts          # TTL-based file cache for parsed documents
├── addons/
│   └── godot-mcp/            # Godot editor plugin
│       ├── plugin.cfg         # Plugin metadata
│       └── plugin.gd          # stdin reader, TCP server, 102 command handlers
├── test/                     # Vitest suite (197 tests: 127 runnable + 70 integration requiring a live Godot project) + legacy .mjs suites
│   ├── test_all.mjs          # Legacy standalone suite (176 tool checks)
│   ├── test_editor.mjs       # Legacy editor bridge TCP tests
│   ├── test_runner.mjs       # Early integration test runner
│   ├── tools.test.ts         # Vitest tool handler tests
│   ├── parsers.test.ts       # Vitest parser tests
│   ├── structural.test.ts    # Vitest structural tests
│   ├── integration_mcp_test.test.ts  # Vitest integration tests
│   ├── server_normalization.test.ts  # Vitest parameter-normalization tests
│   ├── scene_format.test.ts  # .tscn/.tres on-disk format contract (round-trip, hierarchy, ids)
│   ├── addon_bridges.test.ts # GDScript bridge invariants (reserved names, poll(), return types)
│   ├── editor_error_surface.test.ts  # Editor error tagging + undo/redo addon invariants
│   ├── fixtures/             # Test fixture files (.tscn, .tres, .gd)
│   └── test-project/         # Standalone Godot test project
├── scripts/
│   └── sync-addons.js        # Post-build: syncs addons to target Godot project
├── package.json
└── tsconfig.json

Implementation Principles

File-Based Parsing

All Godot file formats (.tscn, .tres, project.godot) are parsed directly in TypeScript using custom parsers. This eliminates the need to launch Godot for file operations, making reads and writes near-instantaneous.

Scene parser (parsers/scene_parser.ts):

• Parses all .tscn sections: [gd_scene], [ext_resource], [sub_resource], [node], [connection]
• Handles multi-line property values with balanced bracket/quote detection
• Builds node hierarchy trees from parent references
• Supports round-trip serialization for safe edits

Resource parser (parsers/resource_parser.ts):

• Parses .tres text resources with section-based structure
• Detects binary .res files via GDROM magic header (returns unsupported error)
• Extracts header, external resources, sub-resources, and main resource properties

Config parser (parsers/config_parser.ts):

• Parses INI-style project.godot and .cfg files
• Handles multi-line values with indentation-based continuation
• Preserves comments for round-trip editing

Dual-Mode Editor Bridge

The editor plugin (addons/godot-mcp/plugin.gd) implements 102 command handlers that wrap Godot's EditorInterface API. Communication uses JSON-RPC 2.0 over two channels:

• TCP mode (port 9876): When Godot is running independently, the plugin accepts TCP connections on 127.0.0.1 only (never the LAN). This is the preferred mode for interactive development. Set GODOT_MCP_TOKEN (or the project setting godot_mcp/auth_token) to require an auth handshake per connection.

• Stdio mode: When the MCP server spawns Godot as a child process (godot --editor --path <project>), the plugin reads JSON-RPC requests from stdin and writes responses to stdout with a __MCP__: prefix marker. The server filters for these markers to distinguish JSON-RPC from Godot's standard output.

The bridge auto-detects which mode to use: it first attempts a rapid TCP health check (800ms timeout), and falls back to spawning Godot if no existing instance is found. If the spawned process exits unexpectedly, it auto-restarts up to 3 times.

Parameter Normalization

To accommodate AI clients that may use either snake_case or camelCase parameter naming, the server automatically normalizes 30+ common parameter names to the snake_case keys its Zod schemas expect (projectPath -> project_path, scenePath -> scene_path, etc.) before validation. The advertised inputSchema always uses snake_case, so snake_case inputs pass through unchanged.

Safety Guarantees

• Path traversal protection: All file operations validate that resolved paths stay within the project root
• Automatic backups: Write operations on script and scene files create .bak backup copies
• Read-only mode: --read-only (or GODOT_MCP_READ_ONLY=true) rejects the 218 write/side-effect tools (write_, create_, delete_, move_, set_, edit_, editor_* mutations, run/export/launch, …) via a maintained whitelist — they are hidden from tools/list and blocked with a READ_ONLY error if called directly
• TCP only on loopback: The editor plugin's TCP bridge binds 127.0.0.1 only, never the LAN
• Optional token auth: Set GODOT_MCP_TOKEN to require a bearer token on HTTP (/mcp, /sse) and an auth handshake on the plugin TCP bridge; non-loopback HTTP binds are refused without it
• Undoable editor mutations: Every scene-changing editor command (editor_add_node, editor_remove_node, editor_set_node_properties, editor_rename_node, editor_move_node, editor_move_node_3d, editor_reparent_node, editor_duplicate_node, editor_delete_selected, editor_instantiate_scene, …) is committed through Godot's native EditorUndoRedoManager, so a single Ctrl+Z (or editor_undo) reverts what the AI just did
• Structured errors: Tool failures return structured { content, isError: true } responses; privileged paths carry typed error codes (READ_ONLY, EDITOR_NOT_REACHABLE, EDITOR_COMMAND_FAILED, NOT_FOUND, …). Engine-side failures are never reported as success — if the editor rejects a command, the tool surfaces EDITOR_COMMAND_FAILED with the engine's own message

Transport Modes

Godot MCP supports three transport protocols. Choose based on your client and deployment needs.

| Mode | Protocol | Use Case | Default | |---|---|---|---| | Stdio | Standard I/O (stdin/stdout) | Local AI clients (VS Code, Claude Desktop, Cursor, Windsurf) | Yes | | SSE | Server-Sent Events over HTTP | Older MCP clients, web-based clients, remote access | | | Streamable HTTP | MCP 2025 Streamable HTTP | Modern MCP clients, production deployments, remote access | |

Stdio (default)

JSON-RPC communication over standard I/O (stdin/stdout). Ideal for local development — no network configuration needed.

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

SSE (Server-Sent Events)

HTTP-based transport using SSE for server-to-client streaming. Compatible with older MCP clients.

npx @yanhuifair/godot-mcp -t sse --port 3000 -p /path/to/your/godot/project

| Option | Description | Default | |---|---|---| | -t sse | Enable SSE transport mode | — | | --port <number> | HTTP listen port | 3000 | | --host <string> | Bind address (use 0.0.0.0 for remote access) | 127.0.0.1 |

Client config:

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://127.0.0.1:3000/sse"
    }
  }
}

Streamable HTTP (MCP 2025)

Modern HTTP transport based on the MCP 2025 spec. Supports session management, reconnection with resume, and both stateful and stateless modes.

npx @yanhuifair/godot-mcp -t streamable-http --port 3000 -p /path/to/your/godot/project

Endpoints:

| Method | Path | Purpose | |---|---|---| | GET | /mcp | Establish SSE stream (supports Last-Event-ID reconnection) | | POST | /mcp | Send JSON-RPC requests/notifications | | DELETE | /mcp | Close session |

Client config:

{
  "mcpServers": {
    "godot-mcp": {
      "url": "http://127.0.0.1:3000/mcp",
      "transportType": "streamable-http"
    }
  }
}

All Transports Simultaneously

npx @yanhuifair/godot-mcp -t all --port 3000 -p /path/to/your/godot/project

Starts: Stdio + SSE (/sse) + Streamable HTTP (/mcp) + Health Check (/health)

curl http://127.0.0.1:3000/health
# {"status":"ok","version":"1.11.2","projectRoot":"/path/to/project","endpoints":{...}}

Installation

Read this first. In normal use you never launch this server yourself — your AI client launches it in the background using the command from its config file. The commands below are for installing the package and for manual/advanced runs (HTTP transports, debugging, CI).

Where to run these commands: from anywhere — but if you pass -p ., the . refers to your current directory, so it must be your Godot project root (the folder containing project.godot). When in doubt, pass an absolute path: -p /full/path/to/project.

Which method should I use?

| Method | Best for | Trade-off | |---|---|---| | npx (recommended) | Almost everyone | Nothing to install; always fetches the latest version. Tiny delay on first run. | | Global install | Slow/offline networks, pinning a version, using a bare godot-mcp command | You must run npm update -g yourself to get new releases. | | From source | Contributing, or you need an unreleased change | You have to rebuild after every git pull. |

Option A — npx (recommended, nothing to pre-install)

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

npx downloads the package on demand and caches it. This is exactly what the config snippets in AI Client Configuration use, so if you follow the Quick Start there is no separate install step at all — -y just skips the "install this package?" prompt.

Option B — Global install

npm install -g @yanhuifair/godot-mcp

# then run it by name anywhere
godot-mcp -p /path/to/your/godot/project

If you install globally, change your client config from "command": "npx" to "command": "godot-mcp" and drop the -y and package name from args:

{ "command": "godot-mcp", "args": ["-p", "."] }

Update later with npm update -g @yanhuifair/godot-mcp.

Option C — From source

git clone https://github.com/yanhuifair/Godot-MCP.git
cd Godot-MCP
npm install
npm run build       # compiles TypeScript into dist/

node dist/index.js -p /path/to/your/godot/project

Point your client at the built entry file:

{ "command": "node", "args": ["/absolute/path/to/Godot-MCP/dist/index.js", "-p", "."] }

Verify your installation

After any install method, confirm everything is in place:

| Check | How | Expected | |---|---|---| | Server version | npx @yanhuifair/godot-mcp --version | A version number (e.g. 1.11.2) | | Plugin files | Look in addons/godot-mcp/ | plugin.cfg, plugin.gd, runtime_bridge.gd | | Plugin enabled | Open project.godot | [editor_plugins] has enabled = PackedStringArray("res://addons/godot-mcp/plugin.cfg") | | Server starts | npx @yanhuifair/godot-mcp -p . (Ctrl+C to stop) | Prints the tool count, e.g. 386 tools | | Editor bridge | Open the project in Godot | Output log shows [Godot MCP] Plugin v… loaded — TCP on 127.0.0.1:9876 |

Install troubleshooting

| Symptom | Fix | |---|---| | npx: command not found | Install Node.js 18+ and make sure it is on your PATH. | | addons/ is still missing after running | You must run in the project root (-p . means the current directory) or pass an absolute -p /path/to/project — see the note at the top of this section. | | Godot still reports an old plugin version | Close Godot, delete addons/godot-mcp, re-run with npx @yanhuifair/godot-mcp@latest --enable-plugin -p ., reopen the project. | | Plugin loads but tools return EDITOR_NOT_REACHABLE | Project → Project Settings → Plugins → make sure Godot MCP is enabled, then reload the project. |

Upgrading to the latest version

npx always fetches the newest release, so the same one-liner that installs also upgrades:

npx -y @yanhuifair/godot-mcp@latest --enable-plugin -p .

To refresh the editor plugin (the files in addons/godot-mcp/), delete the old copy first, then re-run — otherwise stale plugin files can linger:

rm -rf addons/godot-mcp && npx -y @yanhuifair/godot-mcp@latest --enable-plugin -p .

On Windows PowerShell use rm -r addons/godot-mcp (no -f flag).

• Pin a version — npx @yanhuifair/[email protected] …; force latest — npx @yanhuifair/godot-mcp@latest ….
• Global install — npm update -g @yanhuifair/godot-mcp.
• From source — git pull && npm run build.
• Check your version — npx @yanhuifair/godot-mcp --version.

Upgrading from v1.9.0? That release shipped an editor plugin whose runtime_bridge.gd failed to parse in Godot 4.7 (a _input function colliding with the built-in Node._input, plus an untyped _resolve). If your editor logs those parse errors, delete addons/godot-mcp and re-run --enable-plugin to install the fixed plugin.

See CHANGELOG for the complete history. v1.11.2 added export-preset writing (create_export_preset / update_export_preset / remove_export_preset), localization writing (create_po_translation / register_translation / unregister_translation), and a read-only / path-sandbox security pass.

Command-Line Options

| Flag | What it does | |---|---| | -p, --project-path <path> | Your Godot project folder — the one containing project.godot. Auto-detected if omitted. | | -g, --godot-path <path> | Path to the Godot executable. Auto-detected if omitted (see the detection order below). | | --enable-plugin | Copy the editor plugin into addons/ and switch it on in project.godot. Requires -p. This is the one you want. | | --install-addons | Copy the plugin files only — you enable it yourself in Godot's Plugins tab. | | --read-only | Safe mode: rejects the 218 tools that write files or cause side effects. Great for letting an AI explore an unfamiliar project. | | -t, --transport <mode> | stdio (default) · sse · streamable-http · all. See Transport Modes. | | --port <number> | HTTP port for sse / streamable-http. Default 3000. | | --host <string> | HTTP bind address. Default 127.0.0.1. Binding anything else requires GODOT_MCP_TOKEN. | | --no-sse / --no-streamable-http | Disable an individual endpoint when running -t all. | | -h, --help | Print all options and sample client configs. |

# a few real examples
npx @yanhuifair/godot-mcp --enable-plugin -p .          # one-time setup for a project
npx @yanhuifair/godot-mcp -p . --read-only              # let the AI look, not touch
npx @yanhuifair/godot-mcp -p . -t streamable-http --port 8080

Environment Variables

| Variable | Description | |---|---| | GODOT_PATH | Path to Godot binary (optional, auto-detected) | | GODOT_MCP_READ_ONLY | true — enable read-only mode (rejects 218 write/side-effect tools) | | GODOT_MCP_TOKEN | Auth token. HTTP: required when binding a non-loopback host. Plugin TCP bridge: enables the auth handshake on port 9876 | | GODOT_MCP_TEST_PROJECT | Path to test project for integration tests | | GODOT_PROJECT | Target project for the sync-addons build hook | | MCP_STDIO | true — run the editor plugin in stdio mode (set automatically when MCP spawns Godot) |

Godot auto-detection order: GODOT_PATH -> /Applications/Godot.app -> PATH -> snap/flatpak -> Windows Program Files

Security note: The MCP server can read/write your project files, run GDScript, and export builds. When using HTTP transports, always set GODOT_MCP_TOKEN — the server refuses to bind a non-loopback address without it, and loopback-only access is strongly recommended anyway.

AI Client Configuration

Godot MCP is a plain stdio MCP server — anything that speaks MCP can drive it. Below are step-by-step setups for the most popular AI agents, IDEs and CLIs.

In a hurry? Nearly every client wants the same six lines of JSON. Copy the universal snippet, drop it into the file listed for your client, restart, then ask the AI to run get_status. Done.

Pick Your Client

| Client | Where the config lives | Top-level key | |---|---|---| | Claude Code | claude mcp add → .mcp.json | mcpServers | | Cursor | .cursor/mcp.json · ~/.cursor/mcp.json | mcpServers | | VS Code / GitHub Copilot | .vscode/mcp.json | servers | | Codex CLI | ~/.codex/config.toml | [mcp_servers.*] | | Gemini CLI | .gemini/settings.json · ~/.gemini/settings.json | mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | Cline | cline_mcp_settings.json (open via UI) | mcpServers | | Roo Code | .roo/mcp.json · global mcp_settings.json | mcpServers | | Trae | AI panel → MCP (UI) | mcpServers | | Zed | ~/.config/zed/settings.json | context_servers | | JetBrains (Rider / IntelliJ) | Settings → AI Assistant → MCP | mcpServers | | OpenCode | opencode.json | mcp | | Claude Desktop | claude_desktop_config.json | mcpServers | | Continue | ~/.continue/config.yaml | mcpServers | | Cherry Studio | Settings → MCP servers (UI) | mcpServers | | Goose | ~/.config/goose/config.yaml | extensions | | Hermes | ~/.hermes/config.yaml | mcp_servers | | OpenClaw | ~/.openclaw/openclaw.json | mcp.servers | | Reasonix | reasonix.toml · ~/.reasonix/config.toml | [[plugins]] | | WorkBuddy / CodeBuddy | ~/.workbuddy/mcp.json (Connectors panel) | mcpServers | | Aider | .aider.conf.yml | mcp-servers-file | | Anything else | — | see below |

The Universal Snippet

This is the config ~80% of clients accept verbatim:

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

What each part means:

| Field | Why it's there | |---|---| | "godot-mcp" | The name your AI will see. Rename it freely — nothing depends on it. | | "type": "stdio" | The server runs as a local child process. Some clients omit this field entirely; both are fine. | | "command": "npx" | On Windows, if you hit spawn ENOENT, change this to "npx.cmd". | | "-y" | Skips npx's "install this package?" prompt. Without it the server hangs on first run. | | "-p", "." | Your Godot project folder. . means "wherever the client launched the server from". |

When to use . and when to use a full path:

• Editors that open a folder (VS Code, Cursor, Windsurf, Zed, Trae, JetBrains) launch the server inside that folder → "." works, and the config stays portable across machines.
• Desktop apps and global CLIs (Claude Desktop, Cherry Studio, a user-scope Claude Code entry) have no project folder → use an absolute path like "/Users/you/Games/MyGame" or "C:/Users/you/Games/MyGame".
• Windows: always use forward slashes (C:/Users/...) or escaped backslashes (C:\\Users\\...) in JSON.

Two useful variants:

// Read-only — the AI can inspect everything but cannot modify a single file
"args": ["-y", "@yanhuifair/godot-mcp", "-p", ".", "--read-only"]

// Pin the Godot binary when auto-detection fails
"env": { "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot" }

Claude Code

1. Register the server. Run this from inside your Godot project folder:

cd /path/to/your/godot/project
claude mcp add godot-mcp -- npx -y @yanhuifair/godot-mcp -p .

Everything after -- is the command Claude Code will spawn. The -- separator is required — without it Claude Code eats the -y and -p flags as its own.

2. Pick a scope (optional — the default is fine for one project):

| Command | Stored in | Who gets it | |---|---|---| | claude mcp add godot-mcp -- … | ~/.claude.json, keyed by folder | Just you, just this project | | claude mcp add -s project godot-mcp -- … | .mcp.json in the project root | Everyone who clones the repo — commit this | | claude mcp add -s user godot-mcp -- … | ~/.claude.json, global | You, in every project (use an absolute -p path) |

Adding an environment variable:

claude mcp add godot-mcp -e GODOT_PATH=/Applications/Godot.app/Contents/MacOS/Godot \
  -- npx -y @yanhuifair/godot-mcp -p .

3. Verify. Start claude, then type /mcp. You should see godot-mcp with a connected status. Press Enter on it to browse the 386 tools.

4. First prompt:

Run get_status and tell me what the Godot MCP server can currently reach, then list every scene in the project.

Managing it later:

claude mcp list              # all registered servers + connection status
claude mcp get godot-mcp     # full details of one server
claude mcp remove godot-mcp  # unregister

If you used -s project, Claude Code will ask you to approve .mcp.json the first time you open the project. That's a security prompt, not an error — answer yes.

Cursor

1. Create the config. Project-level is best — it travels with the repo:

.cursor/mcp.json in your Godot project root:

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

Prefer it everywhere? Use ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) with an absolute -p path instead.

You can also let Cursor create the file for you: Settings → Tools & Integrations → Add Custom MCP.

2. Verify. Open Cursor Settings → Tools & Integrations. godot-mcp should appear with a green dot and a tool count. Cursor hot-reloads this file, so no restart is needed — if the dot is red, click the refresh icon and check the JSON for a trailing comma.

3. Switch the chat to Agent mode (Cmd/Ctrl+I). Ask mode cannot call tools.

4. First prompt:

Use search_tools to find the tileset tools, then tell me which TileSets exist in this project.

Tool limit warning: Cursor only sends ~40–80 tools to the model at a time. Godot MCP ships 386. Keep search_tools in your rules file (see Make Your Agent Use the Tools Well) so the model looks a tool up instead of hallucinating one.

VS Code / GitHub Copilot

1. Create .vscode/mcp.json in your Godot project root. Note that VS Code's own key is servers, not mcpServers:

{
  "servers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

Shortcut: run MCP: Add Server… from the Command Palette (Cmd/Ctrl+Shift+P) and pick Command (stdio) — VS Code writes the file for you.

2. Start it. VS Code shows a small Start codelens directly above the "godot-mcp" line in the JSON. Click it. (Or run MCP: List Servers → godot-mcp → Start Server.)

3. Switch Copilot Chat to Agent mode. Open Chat (Cmd/Ctrl+Shift+I), then choose Agent in the mode dropdown. Ask and Edit modes don't call MCP tools.

4. Verify. Click the tools icon (🛠) in the chat input — godot-mcp should be listed. If you see "0 tools", run MCP: List Servers → godot-mcp → Show Output to read the startup log.

5. First prompt:

#godot-mcp Run get_status, then list all scenes.

Team tip: commit .vscode/mcp.json. Everyone who clones the repo gets the server automatically — VS Code just asks each person to trust it once.

User-level instead: Command Palette → MCP: Open User Configuration, and use an absolute -p path.

Codex CLI (OpenAI)

1. Add the server with the built-in command (writes ~/.codex/config.toml for you):

codex mcp add godot-mcp -- npx -y @yanhuifair/godot-mcp -p .

Or edit ~/.codex/config.toml by hand — note this is TOML, not JSON:

[mcp_servers.godot-mcp]
command = "npx"
args = ["-y", "@yanhuifair/godot-mcp", "-p", "."]
startup_timeout_sec = 30

[mcp_servers.godot-mcp.env]
GODOT_PATH = "/Applications/Godot.app/Contents/MacOS/Godot"

startup_timeout_sec matters here: npx may need to download the package on the very first run, which can exceed Codex's default startup window.

2. Verify:

codex mcp list

3. Use it — always launch Codex from inside the Godot project so -p . resolves correctly:

cd /path/to/your/godot/project
codex                                        # interactive
codex exec "Run get_status and list all scenes"   # one-shot

Gemini CLI (Google)

1. Add the server:

cd /path/to/your/godot/project
gemini mcp add godot-mcp npx -y @yanhuifair/godot-mcp -p .

Default scope is project → written to .gemini/settings.json. Add -s user to write ~/.gemini/settings.json instead (then use an absolute -p path).

Equivalent hand-written config:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."],
      "timeout": 600000,
      "trust": false
    }
  }
}

• trust: true skips the per-call confirmation prompt. Convenient, but it also means the AI can write files without asking — pair it with --read-only if you want a safety net.
• includeTools / excludeTools accept arrays of tool names if you want to hand the model a curated subset instead of all 386.

2. Verify. Run gemini, then /mcp — it lists connected servers and their tools. gemini mcp list works outside a session.

3. First prompt:

Call get_status, then use search_tools to find animation-related tools.

Windsurf

1. Open the config. Either click Cascade → the hammer icon → Configure, or edit the file directly:

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

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

This file is global, so give it an absolute project path.

2. Refresh. Back in Cascade, click the hammer icon → Refresh. godot-mcp should turn green.

3. First prompt (Cascade is Cmd/Ctrl+L):

Run get_status, then read the main scene.

Cline (VS Code Extension)

1. Open Cline's MCP settings — don't hunt for the file, use the UI: click the Cline icon in the sidebar → MCP Servers (the server rack icon at the top) → Installed tab → Configure MCP Servers. That opens cline_mcp_settings.json.

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. Add the entry:

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

autoApprove takes tool names that should run without a confirmation click — e.g. ["get_status", "search_tools", "list_scenes"] for read-only convenience.

3. Restart. Cline usually reloads on save; if not, click Restart Server next to godot-mcp in the MCP Servers panel. Wait for the dot to go green.

4. First prompt in Plan or Act mode:

Run get_status and summarize this Godot project's structure.

Roo Code (VS Code Extension)

Roo Code supports both a project file and a global file — the project file wins on conflicts.

1a. Project-level (recommended): create .roo/mcp.json in your Godot project root:

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

1b. Global: Roo Code panel → MCP icon → Edit Global MCP (file lives at …/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json). Use an absolute -p path there.

2. Enable it. In the Roo Code MCP panel, make sure the godot-mcp toggle is on and the status dot is green. Hit the refresh icon if it isn't.

3. First prompt:

Use search_tools to find shader tools, then list every .gdshader file.

Trae

Trae has two steps most people miss: adding the server and attaching it to an agent.

1. Add the server. Open the AI side panel → Settings (gear) → MCP → Add → Add manually (or Import from JSON), then paste:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

Wait for the status to become Connected/available before continuing.

2. Attach it to an agent. This is the step that trips people up — Trae agents only see MCP servers you explicitly grant them. Go to Agents → create or edit an agent → Tools → tick godot-mcp, then save.

3. Select that agent in the chat's agent dropdown.

4. First prompt:

Run get_status, then list all scenes in this project.

If the tools never fire, check MCP → godot-mcp → View logs — Trae surfaces the raw stdio startup output there.

Zed

1. Add a local server. Either use the UI — Settings → AI → MCP Servers → Add Server → Add Local Server — or run zed: open settings file from the Command Palette and add:

{
  "context_servers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."],
      "env": {}
    }
  }
}

Zed calls MCP servers context servers — the key is context_servers, not mcpServers. Everything else is the same.

2. Verify. Go back to Settings → AI → MCP Servers. The dot next to godot-mcp should be green with the tooltip "Server is active".

3. First prompt in the Agent Panel:

Use the godot-mcp tools: run get_status, then list the scenes.

Mentioning the server by name meaningfully improves tool-selection accuracy in Zed. For guaranteed usage, create an agent profile that turns off the built-in tools and leaves only godot-mcp on.

JetBrains IDEs (Rider, IntelliJ, GoLand…)

Relevant if you write C# in Rider against a Godot project. Requires a 2025.1+ IDE with the AI Assistant plugin (Junie shares the same MCP config).

1. Open Settings/Preferences → Tools → AI Assistant → Model Context Protocol (MCP).

2. Click +, switch the dialog to As JSON, and paste:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

If your IDE launches processes without your shell's PATH, replace "npx" with the absolute path (which npx / where npx).

3. Apply, then wait for the row to report a tool count instead of an error.

4. Use it in the AI Assistant chat with Codebase/Agent mode enabled — plain chat mode does not call tools.

OpenCode

1. Create opencode.json in your project root (or ~/.config/opencode/opencode.json for all projects):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "godot-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@yanhuifair/godot-mcp", "-p", "."],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Two OpenCode-specific gotchas:

• command is a single array, not command + args.
• The default tool-discovery timeout is 5000 ms. Listing 386 tools plus a cold npx download regularly blows past that — bump it to 30000 as shown or the server will silently show zero tools.

2. Verify. Start opencode in that folder. The MCP server appears at startup; tools are namespaced godot-mcp_*.

3. First prompt:

use godot-mcp to run get_status and list all scenes

Claude Desktop

1. Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Easier route: Settings → Developer → Edit Config opens the file directly.

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

Claude Desktop has no project folder, so the absolute path is mandatory.

2. Fully quit and relaunch. Not "close the window" — quit the app (Cmd+Q / tray → Exit). Claude Desktop reads this file only at startup.

3. Verify. A tools icon appears in the chat input showing the tool count. If it's missing, check the log: ~/Library/Logs/Claude/mcp-server-godot-mcp.log (macOS) or %APPDATA%\Claude\logs\ (Windows).

4. First prompt:

Get the Godot version and list all scenes in my project.

Continue

Continue (VS Code + JetBrains) reads ~/.continue/config.yaml:

mcpServers:
  - name: godot-mcp
    command: npx
    args:
      - "-y"
      - "@yanhuifair/godot-mcp"
      - "-p"
      - "/path/to/your/godot/project"

Older Continue installs use ~/.continue/config.json with a mcpServers array instead — check which file exists before editing. Save, then reopen the Continue panel; tools are discovered automatically. MCP tools only fire in Agent mode.

Cherry Studio

Popular cross-platform desktop MCP client, fully GUI-driven.

1. Settings → MCP Servers → Add Server → Quick create.
2. Name: godot-mcp · Type: STDIO · Command: npx
3. Arguments — one per line, not space-separated:

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

4. Save and toggle the server on. A green indicator plus a tool count means it's live.
5. In a chat, enable the MCP server via the toolbox icon under the input box, then ask it to run get_status.

Import from JSON also works — paste the universal snippet with an absolute -p path.

Goose

Interactive (recommended):

goose configure
# → Add Extension → Command-line Extension
#   Name:    godot-mcp
#   Command: npx -y @yanhuifair/godot-mcp -p /path/to/your/godot/project
#   Timeout: 300

Or edit ~/.config/goose/config.yaml directly:

extensions:
  godot-mcp:
    name: godot-mcp
    type: stdio
    cmd: npx
    args:
      - "-y"
      - "@yanhuifair/godot-mcp"
      - "-p"
      - "/path/to/your/godot/project"
    enabled: true
    timeout: 300

Goose calls MCP servers extensions and uses cmd, not command. Restart Goose, then run /mcp to confirm the connection.

Aider

Aider's MCP support is version-dependent — run aider --help | grep -i mcp first to see which flags your build has.

# Point Aider at a standard MCP JSON file
aider --mcp-servers-file ./mcp.json

# Or inline
aider --mcp-servers '{"mcpServers":{"godot-mcp":{"command":"npx","args":["-y","@yanhuifair/godot-mcp","-p","."]}}}'

./mcp.json is just the universal snippet. Persist it in .aider.conf.yml:

mcp-servers-file: ./mcp.json

Hermes

1. Add via CLI:

hermes mcp add godot-mcp --command "npx" --args "-y" "@yanhuifair/godot-mcp" "-p" "/path/to/your/godot/project"

Or edit ~/.hermes/config.yaml directly:

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

2. Reload and verify. In a session run /reload-mcp, then hermes mcp list / hermes mcp test godot-mcp. Tools appear prefixed mcp_godot-mcp_*.

OpenClaw

1. Add the server (CLI, or Control UI → Settings → MCP → Add server):

openclaw mcp add godot-mcp \
  --command npx \
  --arg "-y" --arg "@yanhuifair/godot-mcp" --arg "-p" --arg "/path/to/your/godot/project" \
  --cwd /path/to/your/godot/project

Or write it directly into ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "godot-mcp": {
        "command": "npx",
        "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."],
        "cwd": "/path/to/your/godot/project",
        "enabled": true
      }
    }
  }
}

2. Verify the connection — a saved definition proves nothing:

openclaw mcp doctor godot-mcp --probe

Restart the Gateway / agent (or openclaw mcp reload) so it picks up the new definition.

Reasonix

1. Add a [[plugins]] entry in reasonix.toml (project) or ~/.reasonix/config.toml (global):

[[plugins]]
name    = "godot-mcp"
command = "npx"
args    = ["-y", "@yanhuifair/godot-mcp", "-p", "."]

2. Restart Reasonix and ask it to call get_status — the godot-mcp_* tools appear in its tool list.

WorkBuddy / CodeBuddy

1. Add a custom MCP connector. Open the Connectors panel → Custom (top-right), and add a server with:

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

This saves to ~/.workbuddy/mcp.json under mcpServers:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

2. Trust it. WorkBuddy keeps a new server inactive until you open it in the connectors list and click Trust. Then start a new session.

3. Verify. Ask:

use godot-mcp to run get_status and list all scenes

Any Other MCP Client

If your client accepts a local command, give it:

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

If your client only accepts a URL (n8n, Dify, browser-based agents, hosted connectors), run the server yourself and point the client at the HTTP endpoint:

export GODOT_MCP_TOKEN="$(openssl rand -hex 32)"   # required for non-loopback binds
npx -y @yanhuifair/godot-mcp -p /path/to/your/godot/project -t all --port 3000

| Endpoint | URL | |---|---| | Streamable HTTP (MCP 2025) | http://127.0.0.1:3000/mcp | | SSE (legacy clients) | http://127.0.0.1:3000/sse | | Health check | http://127.0.0.1:3000/health |

See Transport Modes for the full details.

Make Your Agent Use the Tools Well

386 tools is more than most models can keep straight, and many clients only forward a slice of them to the model. Two minutes of setup fixes this.

1. Drop a rules file in your project. Agents auto-read these: AGENTS.md (Codex, OpenCode, Cursor, Gemini CLI, Zed), CLAUDE.md (Claude Code), .cursor/rules/*.mdc (Cursor), .clinerules (Cline / Roo Code), .github/copilot-instructions.md (Copilot).

## Godot MCP

This project has the `godot-mcp` server attached (386 tools).

- Never guess a tool name. Call `search_tools` with a keyword first —
  e.g. search_tools("tileset"), search_tools("animation"), search_tools("navmesh").
- On `EDITOR_NOT_REACHABLE` or `RUNTIME_NOT_REACHABLE`, call `get_status`
  and tell me what's missing instead of retrying blindly.
- On `EDITOR_COMMAND_FAILED`, the editor rejected the command — read the
  engine message, verify the node path / property with `editor_get_scene_tree`
  or `get_class_properties`, then retry. Do not repeat the same call.
- Every `editor_*` scene change is undoable — if I say "undo that",
  call `editor_undo` rather than trying to reconstruct the old state.
- Prefer the file tools (read_scene, write_script, create_resource…).
  They work with Godot closed and are the fastest path.
- Use `editor_*` tools only when the change must show up in a live editor.
- Use `runtime_*` tools only after the game is actually running (F5).
- Always `read_scene` before `add_node` so the parent NodePath is correct.
- Read a script before rewriting it; never blank a file you haven't read.

2. Let it look before it touches. For a first run on an unfamiliar project, add --read-only to args. The server then rejects every write tool at the boundary, so no amount of enthusiasm from the model can damage your project.

3. Two prompts worth memorizing:

get_status — what is currently reachable (editor? running game?) and how many tools are loaded. search_tools("<keyword>") — the right tool name, ranked, without burning context on a 386-item list.

Troubleshooting

| Symptom | Cause & fix | |---|---| | No tools show up at all | The client is in Ask/Chat mode. Switch to Agent mode — most clients don't call tools otherwise. | | Server "fails to start", no error | JSON syntax. A trailing comma or a smart quote from a copy-paste is the usual culprit — validate the file. | | spawn npx ENOENT (Windows) | Change "command": "npx" to "npx.cmd", or use the absolute path from where npx. | | spawn npx ENOENT (macOS/Linux GUI apps) | The app launched without your shell PATH. Use the absolute path from which npx. | | Server times out on first launch | npx is downloading the package. Run npx -y @yanhuifair/godot-mcp --help once in a terminal to warm the cache, and raise the client's startup timeout. | | Project not found | -p . only works when the client's working directory is the Godot project. Switch to an absolute path. | | Connected, but 0 tools | Tool-discovery timeout too low (notably OpenCode's 5 s default). Raise it to 30 s. | | File tools work, editor_* tools fail | The editor plugin isn't running. Run --enable-plugin, reload the project in Godot, and check get_status. | | RUNTIME_NOT_REACHABLE | The game isn't running, or the runtime autoload isn't registered. See Tool Discovery & Live Game Runtime. | | Godot can't be found | Set GODOT_PATH in the config's env block to the Godot binary. | | Model picks the wrong tool | Add the rules file above, and tell it to call search_tools first. | | Node.js too old | node -v must be ≥ 18. |

Usage Examples

The following examples show what you can ask your AI assistant. Each maps to one or more MCP tools (shown in parentheses).

Project Exploration

| Command | Tools Used | |---|---| | "Show me the project structure" | list_project_files | | "Generate a project overview report" | generate_project_report | | "What autoloads are configured?" | list_autoloads | | "Check my project for broken references" | validate_project | | "Find unused assets I should clean up" | find_unused_assets |

Scene Creation and Editing

| Command | Tools Used | |---|---| | "Create a 2D platformer scene with a CharacterBody2D root" | create_scene | | "Add a Cooldown Timer node under the Player" | add_node | | "Clone the Enemy node as Enemy2" | clone_node | | "Connect body_entered signal from Player to _on_body_entered" | connect_signal | | "Set the Player collision shape to CapsuleShape2D" | set_collision_shape | | "Load the player.png texture onto the Sprite" | load_sprite | | "Search all scenes for Timer nodes" | find_nodes_in_scenes | | "List all Button and Label nodes" | list_ui_nodes |

Script and Shader

| Command | Tools Used | |---|---| | "Analyze the structure of player.gd" | read_script_structure | | "Add a dash method to the Pla