Godot MCP Server

The npm bridge that connects AI coding assistants to the Godot 4.2+ editor over the Model Context Protocol. Your assistant can create scenes, edit scripts, inspect nodes, run playtests, and read the results back, directly inside the editor while you watch. It pairs with the Godot MCP Toolkit editor plugin, which hosts the WebSocket servers this bridge talks to.

Runs fully locally. No telemetry, no cloud services, no account. Nothing leaves your machine.

This is an independent community project, not affiliated with or endorsed by the Godot Foundation or Anthropic.

Desktop only: Windows, macOS, and Linux. Requires Node.js 22 or newer.

📐 Architecture → covers how the server is built: the entrypoint and startup, the WebSocket bridge, the catalogue and dispatch pipeline, discover_tools, the GDScript LSP client, and the registry consumer. Also rendered at npgamedev.github.io/godot-mcp-server/architecture.

Why this one?

Built to fit your workflow, not the other way around.

The number that says the most is 150+ operations. That is the real work on offer: create a node, paint a tilemap cell, key an animation track, read a live node mid-playtest, and roughly a hundred and fifty more. Those operations are packaged into up to 113 tools (an always-on core plus 28 on-demand groups), because a tool is a slot in your client’s tool budget and an operation is a thing you can actually do. Related actions sit behind one tool, which keeps the list short while the operation count tells the honest story of breadth. Some operations are version-gated, so older Godot versions (down to 4.2) expose fewer. “Up to” is literal.

Two things drive the design, and they carry equal weight:

• You can extend it without a fixed ceiling. The toolkit’s extension API lets a project register its own tools in GDScript. They hot-reload and reach the agent through this bridge exactly like built-ins, and there is no fixed cap on how many you add. The limit is what the current system supports, and each iteration raises that ceiling and gives extensions more room. C#/.NET projects extend the same way, which is the proof that this fits every project instead of being a bolt-on. Heuristic or third-party-dependent tools stay out of the core on purpose, and the extension API is where they belong.
• You can check the results. The agent’s context window is a budget, so the tool surface starts small (~9,500 tokens) and grows only when the agent asks for more. The evidence section below says what CI asserts on every build, what the test manifests cover, and what was measured when. Links, not adjectives.

Tested primarily with Claude Code, and compatible with any MCP client.

Quick start

1. Install the bridge

npm install -g @npgamedev/godot-mcp-server

Requires Node.js 22 or newer (node --version to check). Clients can also run it without a global install via npx -y @npgamedev/godot-mcp-server, which is the form the config files below use.

2. Install and enable the Godot plugin

Install the Godot MCP Toolkit from the Godot Asset Store (or GitHub Releases), then enable it: Project Settings → Plugins → Godot MCP Toolkit → Active.

You should see: the MCP dock appears, and the Output log prints

[MCPServer] listening on 127.0.0.1:6550

(the port may land anywhere from 6550 to 6560; the dock’s status section names the live one).

3. Configure your MCP client

The easiest path: let the plugin write the config. Project → Tools → MCP Toolkit → Write .mcp.json creates a correct .mcp.json at your project root (Windows wrapper included), and the dock keeps it healthy.

For every other client (Claude Desktop, Cursor, Windsurf, VS Code, Cline, Codex CLI, Gemini CLI) and the per-OS gotchas, use the client setup guide. It is the canonical setup matrix.

macOS, launching your client from Finder/Dock? The standard config connects either way for modern clients. If yours won’t, the client setup guide has the fix, from PATH diagnosis to the safe fallbacks.

4. Connect and ask for something

Launch your MCP client from the project root. The server discovers the plugin through a shared project registry and authenticates with a per-session token automatically.

Then try the first prompt below. This is the kind of result it produces:

If a step does not produce its “you should see”, head to the troubleshooting guide. It starts with a 60-second checklist and a connectivity probe.

Try asking…

1. “Build a small brick-breaker: paddle, ball, a wall of bricks, a score label, and a game-over screen, then playtest it.”
2. “Add a CharacterBody2D named Player to the main scene, with a Sprite2D and a CollisionShape2D under it.”
3. “Create a main menu scene with a Start button that switches to the game scene when clicked.”
4. “Run the game, then tell me the Player’s position and velocity while it’s running.”

The last three run in seconds. The first one is a real project, the same kind of small game we build end-to-end when validating a release, in a single agent session. Larger games span multiple sessions, with or without MCP.

The brick-breaker from prompt 1 above.

What the tools cover

The always-on core handles the everyday work: scenes, nodes, scripts, project settings, playtests, screenshots, input simulation, code execution. Specialized surfaces load on demand, and the assistant activates them mid-session with discover_tools, by keyword or by name:

Those 28 groups are the built-in surface. A project can add more: register your own tools through the toolkit’s GDScript extension API and they reach the agent through this bridge like any built-in, with no fixed cap on how many, and the ceiling only rises as the toolkit grows.

The authoritative per-tool list (every tool, operation, parameter, and version gate) is the generated tool reference. Which tools exist on which Godot version is in the shipped compatibility guide.

Tested on: Godot 4.2–4.7.x

How it is designed

A few deliberate choices shape the tool surface:

• Consolidated tools, counted operations. Related actions share one tool with an action parameter instead of one tool each. The short tool list fits every client’s tool budget and costs fewer context tokens; the 150+ operation count is what says how much the toolkit can really do.
• Read/write discipline. Every tool carries read-only and destructive annotations, so clients can auto-allow safe tools and gate risky ones. Read-only mode can hide every mutating tool with one switch.
• Two channels. The bridge dials the Editor channel (the WebSocket server inside the editor) for authoring, and the Runtime channel (the server inside the running game) during playtests. One side channel, the GDScript language-server client, connects to Godot’s LSP directly.
• Registry-driven discovery. Every endpoint (editor port, runtime port, LSP, auth token) resolves from the plugin’s machine-wide project registry, so there is no blind port scanning and no manual setup for multiple editors or git worktrees.
• Version-adaptive. Tools degrade gracefully across Godot 4.2 to 4.7: version-gated tools are filtered from the list rather than failing cryptically, and the surface completes itself once the editor’s version is known.

Configuration

Everything works with zero configuration; the registry handles discovery. The variables below override the dial (connect) side. The listen side (the ports the editor and game bind) is configured on the plugin: see the shipped advanced configuration guide.

Environment variables

CLI flags

Dial-target overrides, resolved with precedence CLI flag > env var > registry discovery > default:

Both --flag value and --flag=value forms are accepted.

Multiple editors / pinned ports

With no configuration, the server discovers each editor’s port through the shared project registry, so parallel editors and git worktrees need no setup. Pin a port only when you need a deterministic setup (CI, containers).

[!IMPORTANT] A pinned port must be pinned on both sides with the same value: the editor binds where its environment says, and the server dials where yours says. An environment variable is not a sync channel. It is two independent per-process reads, and the common failure is .mcp.json pinning the server while the editor launches without the value (a desktop shortcut does not inherit a shell’s export). The server fails fast with a message naming the mismatch instead of hanging; if you don’t want to manage this, don’t pin.

Read-only mode

For supervised environments (classrooms, CI, demos, reviewing an unfamiliar project), set GODOT_MCP_READ_ONLY=1 in the server’s env. Every mutating tool is left unregistered, absent from the tool list entirely, no matter what the client or the model asks for. Turn it off and reconnect the client to restore full access; the tool list is decided at connect time. For per-tool permission rules on top (auto-allowing reads, prompting on writes), see the permissions section of the client setup guide.

Headless mode

Most tools work under godot --headless --editor: file, scene, node, script, ClassDB, and project tools all function without a display. Screenshot tools return HEADLESS_UNSUPPORTED, and everything that needs a running game degrades with clear errors (a headless environment has no display for the game process to present). The canonical per-tool headless matrix is in the shipped compatibility guide.

Token efficiency

The tool catalogue consumes context-window tokens, so the surface starts small and grows on demand: the startup surface costs ~9,500 tokens, the full surface (every group activated) ~29,100, and read-only mode ~8,700. Per-group costs, the measurement method, and the regeneration command are in docs/token-efficiency.md.

How we know it works

CI fails the build if any of these numbers drift: 113 tools (34 always-on + 2 meta, 79 on-demand) in 28 groups, covering 150+ operations; 40 tools visible in read-only mode.

• Every tool has smoke coverage (happy path, guards, error hints), mapped in the smoke coverage manifest. Cross-tool stateful flows run as their own deterministic suite (npm run flows), and dispatch behavior (mutation serialization, cancellation, disconnects) as another. Separate suites, separately maintained.
• Every tool is also exercised end-to-end from GDScript in the toolkit’s interactive sweep, mapped in the sweep coverage manifest. Last full pass: 479 cases on Godot 4.7 (2026-07-03).
• CI exercises Godot 4.2 through 4.7, on Windows, macOS, and Linux, in both GDScript and C# (mono) editors. The floor (build, unit tests, lint, format, and the static catalogue gate) runs on every push; the full behavioral matrix is an opt-in deep tier, and headless-incompatible sections (screenshots, display-bound input) are skipped there and validated locally.
• An accuracy eval suite (npm run eval) validates tool-call correctness and workflow efficiency against a live editor: “does it work well”, separate from smoke’s “does it work”.
• Five small games (a clicker, a brick-breaker, chess, a platformer, and a tower defense) were each built end-to-end in a single agent session as release validation.
• The bundled workflow skill was measured in a controlled two-wave run (same game, with and without the skill, at one version): see companion-skill efficiency.
• Concurrent human + AI editing is validated for specific scenarios: creating nodes during manual scene-tree edits, undo interleaving, editing a node while its Inspector is open, and mid-drag reparenting. Complex viewport interactions may benefit from taking turns.

Known limitations

• Dynamic tool loading needs a client that processes tools/list_changed. Tools activated mid-session via discover_tools appear only if the MCP client handles that notification. Current Claude Code versions do, in both interactive and pipe (claude -p) mode (verified 2026-07-19); earlier versions did not process it in pipe mode. If newly activated tools do not appear, reconnect or upgrade the client, or call extensions_refresh to force a re-sync of extension tools.
• Screenshot capture size. A full-size viewport capture (a 3D viewport especially) can exceed the WebSocket transport buffer and fail with RESPONSE_TOO_LARGE. Pass image_response_mode: "disk" to save the PNG and receive its path, or request a lower image_detail.

Security

The default posture is localhost-only, token-authenticated, and auditable:

• Session auth. Random 64-char hex token per plugin start; unauthorized connections rejected.
• Filesystem sandbox. res:// only by default; path traversal blocked (lexical canonicalization, plugin-side), with a fast server-side pre-filter.
• Read-only mode. GODOT_MCP_READ_ONLY=1 hides every mutating tool, enforced here server-side.
• Audit log. Every tool call logged with timestamp and parameter hash.
• Response caps. Size-limited reads prevent accidental data exfiltration.
• Untrusted envelopes. Per-call nonce-tagged wrappers mitigate prompt injection.
• Localhost only. 127.0.0.1 bind on every socket; never 0.0.0.0.

Vulnerability reporting and isolation guidance (containers, VMs, restricted accounts) are in SECURITY.md. Per-tool risk notes and recommended client-side permission rules: the shipped security recommendations; a ready-made Claude Code allow-list example is in the client setup guide.

Disclaimer: We design every layer with defense-in-depth, but no software is immune to misuse or unforeseen vulnerabilities. This project is provided under the MIT License with no warranty. You are responsible for evaluating whether it meets your security requirements before use.

Architecture

┌─────────────┐          ┌─────────────────────┐          ┌────────────────────┐
│  MCP client │─ stdio ─>│  godot-mcp-server   │─ ws ────>│  godot-mcp-toolkit │
│  (AI agent) │          │  (this package)     │  :6550   │  (Godot plugin)    │
└─────────────┘          └─────────┬───────────┘          └─────────┬──────────┘
                                   │                                │
                                   └──── ws :6570 (runtime) ───────>│
                                         (the running game)        (autoload)

• Editor channel (default port 6550) operates on the edited scene via EditorInterface.
• Runtime channel (default port 6570) operates on the live SceneTree in the running game. Auto-connected when game_start runs with wait_for_runtime: true.

Port discovery is automatic via the shared project registry; auth tokens resolve per project (and per worktree). The full story (startup, transport, dispatch, security boundaries, with diagrams) is in docs/architecture/README.md.

FAQ

Documentation

• Documentation map: every doc, organized by what you want to do.
• Client setup: per-client configuration with per-OS paths and gotchas.
• Tool reference (generated): every tool, operation, parameter, and version gate.
• Token efficiency: the measured context cost of the tool surface.
• Companion-skill efficiency: the measured build-time savings from the bundled workflow skill.
• Testing locally: every test layer and how to add coverage.
• Troubleshooting: 60-second checklist, connectivity probe, symptom-to-fix entries.
• Architecture: subsystems, transport, contract surface, with diagrams.

Contributing

See CONTRIBUTING.md for environment setup, the test layers, and the documentation rules.

Releases

This project follows Semantic Versioning. The toolkit plugin and the MCP server bridge are versioned independently; install the latest of each and they negotiate compatibility at connect (see RELEASING.md → Compatibility).

• npm: npm install -g @npgamedev/godot-mcp-server@latest
• Godot Asset Store: Godot MCP Toolkit. Godot 4.7: in the editor’s Asset Store tab, search “Godot MCP Toolkit”, Download, Install. Godot 4.2–4.6: download the zip from the store page, then install it with the AssetLib tab’s Import… button.
• GitHub Releases: download from either repo’s Releases page for manual installation

See RELEASING.md for maintainer release process and version policy.

Author

NPGameDev · npgamedev.com · GitHub

For inquiries and requests: [email protected]

Trademarks

Godot and the Godot logo are trademarks of the Godot Foundation. This bridge is an independent community project with no affiliation with or endorsement from the Foundation, and it is not an official Godot product. The name describes what the bridge connects to: the Godot Engine.

License

MIT: see LICENSE. Upstream notices in ATTRIBUTIONS.md.