godot-dev-mcp

English · 中文

Safe, composable MCP (Model Context Protocol) gateway for Godot: scene authoring, read-only runtime diagnostics, and allowlisted verification.

Current version is 0.2.0. Python 3.11+ is required.

Contents

• What it is

• Architecture

• Capability boundaries

• Quick start

• Observer connections

• Tools

• Project config and VERIFY

• Verification status

• Safety boundaries

• License and sources

Related MCP server: godot-ai-mcp

What it is

godot-dev-mcp lets MCP clients such as Codex inspect and change Godot projects with structured tools, instead of guessing .tscn formats or running arbitrary commands.

The MCP server uses standard stdio transport: one UTF-8 JSON-RPC message per line. It supports requests, notifications, and batches, and never writes non-protocol content to stdout.

Architecture

flowchart LR
  Client["MCP Client<br/>Codex / Claude"] -->|stdio JSON-RPC| Server["godot-dev-mcp<br/>Python 3.11+"]
  Server -->|"AUTHOR: inspect / dry-run patch"| Project["Godot project<br/>.tscn .gd .tres"]
  Server -->|"OBSERVE: HTTP GET loopback"| Editor["Editor Observer<br/>127.0.0.1:7331"]
  Server -->|"OBSERVE: HTTP GET loopback"| Runtime["Runtime Observer<br/>127.0.0.1:7332"]
  Server -->|"VERIFY: allowlisted argv"| Checks["project checks<br/>Stagehand adapter"]
  Addon["addons/godot_dev_mcp"] --> Editor
  Addon --> Runtime

Capability boundaries

Quick start

1. Install the Python package

git clone https://github.com/DLeungDL/godot-dev-mcp.git
Set-Location godot-dev-mcp
python -m pip install -e .
python -m unittest discover -s tests -v

2. Enable the Godot addon

Copy addons/godot_dev_mcp from this repository into the target Godot project's addons/ folder. In Godot, open Project Settings → Plugins and enable godot-dev-mcp Observer.

Enabling the addon also registers the GodotDevMCPRuntimeObserver autoload. Restart the Godot Editor after the first install or an addon update so Observer loads in normal editor sessions.

3. Start the MCP server

To inspect the scene tree in the Godot Editor, use the default Editor Observer:

python -m godot_dev_mcp.server --project "C:\path\to\godot-project"

To inspect a running game, start the game from Godot first, then connect Runtime Observer:

python -m godot_dev_mcp.server `
  --project "C:\path\to\godot-project" `
  --bridge-url "http://127.0.0.1:7332"

4. Connect Codex

[mcp_servers.godot_dev]
command = "python"
args = ["-m", "godot_dev_mcp.server", "--project", "C:\\path\\to\\godot-project"]
cwd = "C:\\path\\to\\godot-dev-mcp"

To connect a running game, change args to:

args = [
  "-m", "godot_dev_mcp.server",
  "--project", "C:\\path\\to\\godot-project",
  "--bridge-url", "http://127.0.0.1:7332"
]

Observer connections

Quick health checks:

Invoke-RestMethod http://127.0.0.1:7331/health
Invoke-RestMethod http://127.0.0.1:7332/health

Runtime Observer starts in debug builds only. To enable it in a release build, set:

godot_dev_mcp/allow_release_observer=true

Change the runtime port with godot_dev_mcp/runtime_port. If you change the port, the MCP server --bridge-url must match.

Runtime Observer uses a custom Godot Logger to capture engine messages, push_warning(), push_error(), script errors, and shader errors. Logger callbacks enqueue work under a Mutex; the main thread then writes a ring buffer of at most 500 entries. Screenshots need a display server; headless mode returns 503 Service Unavailable.

Tools

godot_scene_patch defaults dry_run to true. A write happens only when you pass false, and only for a single .tscn property. Node selectors accept a name, relative path, or full scene path; ambiguous names are rejected. Replacing an existing multiline property removes the full old value. The result includes the resolved scene_path plus a before/after change summary.

godot_scene_inspect returns bounded structured_nodes with node name, type, parent, scene path, and up to 100 properties. Multiline properties keep their full serialized form. Each value is capped at 4,096 characters, each node at 32,768 characters, and the whole scene at 131,072 characters. Truncated items are listed in truncated_properties. Pass an optional node selector to get an exact selected_node by name or scene path; use the full path when the name is not unique.

godot_runtime_snapshot returns a depth-first flat nodes page with pagination:

• Default limit=100, maximum 500

• Use next_offset for the next page

• max_depth maximum is 16

• offset maximum is 100000

Project config and VERIFY

Copy examples/godot-dev-mcp.example.json to godot-dev-mcp.json at the target project root, then edit it for that project.

{
  "checks": {
    "smoke": ["godot", "--headless", "--path", ".", "--quit-after", "60"]
  },
  "stagehand": {
    "command": ["godot-stagehand", "run", "--out-dir", "stagehand-artifacts"],
    "junit": "stagehand-artifacts/junit.xml",
    "report": "stagehand-artifacts/report.json",
    "visual_diff": "stagehand-artifacts/visual-diff.json"
  }
}

• Check names are the allowlist accepted by godot_run_check.

• Commands must be non-empty string arrays and start with shell=false.

• Timeouts are 1–900 seconds.

• Stagehand stays a separate adapter; this project only passes a scenario and parses structured artifacts.

• A Stagehand scenario example is in examples/auction-ui.stagehand.json.

Verification status

CI in this repository runs:

• Python unit tests and MCP stdio subprocess integration tests

• Python compileall plus wheel/sdist packaging

• Godot 4.7.1 Mono headless Editor addon load

Runtime Observer has also been checked against the official 2d/dodge_the_creeps demo: it can read a real game scene tree, performance monitors, and structured runtime errors.

The version 2 integration roadmap is in Issue #1.

Safety boundaries

• Project paths are resolved and path traversal is rejected.

• The observation bridge must use HTTP loopback.

• Runtime properties are limited to engine properties; script-defined properties are not exposed.

• Lists, process output, tree depth, snapshot pages, and log buffers are all bounded.

• There is no arbitrary shell command, arbitrary file-read, or runtime write interface.

• Project-specific extensions are off by default; the generic core does not depend on game-specific code.

License and sources

This project is MIT licensed and is a clean-room implementation. Interface review and attribution for external projects are in THIRD_PARTY_NOTICES.md.