# Godot MCP

A safe, standards-compliant [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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:

```jsonc
{
  "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`](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

```bash
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.