Godot MCP

A safe, standards-compliant Model Context Protocol server for the Godot Engine editor. It lets an AI client (Claude, etc.) read a Godot project, author scenes/nodes/scripts, run the game and read diagnostics — through a transactional, permission-controlled kernel that maps every operation onto real Godot editor APIs (EditorInterface, EditorFileSystem, EditorUndoRedoManager, ProjectSettings, ResourceLoader/Saver).

This project is a Godot reimplementation of the cocos-mcp design: the same layered architecture (contracts → core/execution kernel → adapter → editor), the same safety model (typed I/O schemas, dry-run, optimistic revision, permission tiers, audit), adapted to Godot's object model.

MCP client (Claude …)
   │  stdio (JSON-RPC)
@godot-mcp/mcp-server  ── ExecutionKernel ── ToolRegistry ── Policy
   │  newline-delimited JSON-RPC over TCP (127.0.0.1:6040)
addons/godot_mcp (GDScript EditorPlugin)
   └─ EditorInterface / EditorFileSystem / EditorUndoRedoManager

Why this shape

Faithful to the editor. Every tool resolves to a real Godot API in the addon. No hand-editing of .tscn/.import/.godot internals.
Godot's addressing, not Cocos's. Nodes are addressed by NodePath (scene-relative, e.g. /Player/Sprite); resources/scripts/scenes by res:// paths. There are no UUIDs to keep in sync.
Safe by default. read/write on, destructive/build off. Writes are serial, undoable, dry-run-able, revision-checked and audited.
Stable, machine-readable results. Tools never return ad-hoc { success: false }; failures carry a stable error.code.

Repository layout

packages/
  contracts/       Zod schemas, domain types, the GodotAdapter contract
  core/            ToolRegistry, ExecutionKernel, PolicyEngine, operations, audit, tools
  godot-adapter/   TCP JSON-RPC bridge + GodotAdapter implementation
  testkit/         In-memory Godot adapter for tests
apps/
  mcp-server/      Standalone stdio MCP server CLI
  godot-editor-addon/  GDScript EditorPlugin (addons/godot_mcp)
docs/              ARCHITECTURE, GODOT_INTEGRATION, TOOL_SPECIFICATION

Quickstart

1. Build the server

pnpm install
pnpm build          # -> dist/mcp-server/index.js
pnpm test           # unit/integration tests

Requires Node.js ≥ 20.19.

2. Install the editor addon

Copy apps/godot-editor-addon/addons/godot_mcp into your Godot 4 project:

<your-project>/addons/godot_mcp/   (plugin.cfg, plugin.gd, bridge.gd, rpc_handler.gd)

In Godot: Project → Project Settings → Plugins → enable "Godot MCP". On enable the plugin starts a TCP bridge on 127.0.0.1:6040 (printed to the editor output). Restart it any time via Godot MCP: Restart server in the tool menu.

Targets Godot 4.2+ (tested profile: 4.3). The addon only uses public, stable editor APIs.

3. Connect your AI client

Add the server to your MCP client config. For Claude Code / Claude Desktop:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "node",
      "args": ["<repo>/dist/mcp-server/index.js"],
      // optional:
      // "env": { "GODOT_MCP_ADDON_URL": "tcp://127.0.0.1:6040" }   // default
    },
  },
}

CLI flags: --addon-url tcp://host:port, --profile readonly|standard|trusted.

4. Use it

Ask the model: "What's in the current scene?" → it calls system_status, then node_query/node_get. "Add a Player node with a Sprite2D child and a script" → it dry-runs scene_build, then applies it. "Run the game and tell me if there are errors" → run_start (needs the trusted profile), then logs_query.

Tools (25)

Domain	Tools
System / project	`system_status`, `project_get`
Scene	`scene_list`, `scene_get`, `scene_open`, `scene_save`, `scene_create`, `scene_build`
Node / property	`node_query`, `node_get`, `node_create`, `node_update`, `node_reparent`, `node_duplicate`, `node_delete`, `property_set`
Script	`script_read`, `script_write`
Asset	`asset_query`
Selection	`selection_get`, `selection_set`
Run	`run_status`, `run_start`, `run_stop`
Logs	`logs_query`

Read tools are read tier. Writes are write tier and support dryRun, expectedRevision and idempotencyKey. node_delete is destructive; run_start/run_stop are build (both off by default).

Full per-tool schemas and semantics: docs/TOOL_SPECIFICATION.md.

Permission profiles

Profile	Grants	Notes
`readonly`	read only	Safe to share
`standard` (default)	read + write	Author scenes/scripts
`trusted`	read + write + destructive + build	Run game, delete nodes

deny always wins; confirm returns CONFIRMATION_REQUIRED. Permissions are server-enforced on every call, independent of what the client advertised.

Development

pnpm typecheck     # tsc --noEmit across the workspace
pnpm test          # vitest
pnpm lint          # eslint
pnpm format        # prettier
pnpm verify        # format:check + lint + typecheck + test + build

Status & limitations (v1)

Godot 4.2+ only. Godot 3 is not supported.
Loopback only. The bridge binds 127.0.0.1; do not expose it.
Logs are the editor-side buffer. v1 does not capture the running game's stdout; logs_query returns the addon's own ring buffer. Use the editor Output panel for full runtime logs.
Cross-call undo. Each write RPC records its own EditorUndoRedoManager action, so Ctrl+Z works in the editor. A write that fails mid-flight is reported failed_dirty — undo it manually rather than retried blindly.
No arbitrary code execution. There is no eval/execute-script tool. script_write writes .gd files under res:// only.

License

MIT.

godot-mcp