(((((((             (((((((
                    (((((((((((           (((((((((((
                    (((((((((((((       (((((((((((((
                    (((((((((((((((((((((((((((((((((
     (((((      (((((((((((((((((((((((((((((((((((((((((      (((((
   (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
  ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
    (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
       (((((((((@@@@@@@(((((((((((((((((((((((((@@@@@@@@((((((((((
       ((((((@@@@,,,,,@@@((((((((((((((((((((@@@,,,,,@@@@(((((((((
       (((((@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
       ((((((@@,,,,,,,@@(((((((@@@@@((((((((@@,,,,,,,@@@(((((((((
       (((((((((@@@@@@(((((((((@@@@@(((((((((((@@@@@@((((((((((((
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
       @@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@
       (((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ ((((((((
       ((((((((( @@(((((((((@@@(((((((((((@@@((((((((((@@ (((((((((
        ((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@((((((((((
         ((((((((((((((((((((((((((((((((((((((((((((((((((((((((
            (((((((((((((((((((((((((((((((((((((((((((((((((
                    (((((((((((((((((((((((((((((((((

          G O D O T    x    M O D E L   C O N T E X T   P R O T O C O L

Fork of Coding-Solo/godot-mcp, extended with interactive game control, persistent TCP communication, script authoring, automated tests, and more.

• 75 tools covering the full game-dev loop: projects, scenes, nodes, scripts, resources, tilemaps, animation, settings, exports
• Interactive play-testing — run the game, send keyboard/mouse/gamepad input, query live state, wait for signals, capture the viewport
• Batched test sequences — keys, waits, screenshots, state snapshots, and signal collection in a single round-trip
• Stateless MCP 2026-07-28 on SDK v2 — no handshake for modern clients, cached tool lists, automatic fallback for 2025-era clients
• Safety controls — toolset filtering, read-only mode, and per-tool exclusion via environment variables
• Fully tested — 184 automated tests against a real headless Godot engine, no mocks

MCP (Model Context Protocol) is a standard that lets AI assistants use external tools. Think of it like a USB port — your AI plugs into this server and gains the ability to control Godot.

You (natural language) --> AI Assistant --> MCP Server --> Godot Engine
    "Add a player to           |              |              |
     the scene"            interprets     calls tool     creates node
                           your request   add_node()     in .tscn file

You talk to your AI assistant normally. When it needs to do something in Godot, it calls one of the 75 tools this server provides. You don't write any code yourself — the AI handles that.

git clone https://github.com/Vollkorn-Games/godot-mcp.git
cd godot-mcp
pnpm install
pnpm run build

Note the full path to build/index.js — you'll need it below.

Every config needs the same two things: the command to start the server (node + path to build/index.js) and the GODOT_PATH environment variable pointing at your Godot executable.

claude mcp add godot -- node /absolute/path/to/godot-mcp/build/index.js

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/absolute/path/to/godot/executable"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/absolute/path/to/godot/executable"
      },
      "disabled": false
    }
  }
}

Open your AI assistant and try:

"Use the get_godot_version tool to check if the MCP server is connected."

If it returns a version number, everything is working. Now try:

"Create a new Godot project at C:/Users/you/my-game with a Node2D main scene."

This isn't just "launch editor and read logs". The server can build an entire game from scratch — create scenes, add and configure nodes, write GDScript files, wire up signals, set up tilemaps — then run the game, play it via input commands, and observe the results through screenshots and state queries.

75 tools across 10 categories:

The standout feature. run_interactive injects a TCP server into the running game as a temporary autoload, giving the AI a live, two-way channel to the game:

The TCP connection is persistent (single socket reused across commands). Everything is cleaned up automatically when the game stops — the injected autoload is removed and project.godot is restored.

send_key_sequence is the primary tool for gameplay testing. It bundles keys, InputMap actions, waits, state snapshots, screenshots, and signal collection into a single round-trip — much faster than calling individual tools in a loop.

Fast gameplay test (1 round-trip):

send_key_sequence({
  keys: ["1", {"action": "move_right", "hold_ms": 300}, {"state": true}, "o", {"wait": 2000}, {"screenshot": "mid.png"}, "s"],
  collectSignals: [{nodePath: "/root/EventBus", signals: ["task_completed", "score_changed"]}]
})
// Response includes:
//   keys_sent: 4
//   states: [{state: {scene: "Desktop", score: 100}, index: 2}]
//   screenshots: [{path: "mid.png", size: "1024x768", index: 3}]
//   events: [{signal: "score_changed", node: "/root/EventBus", args: [200]}]

Avoid these slower patterns:

// BAD: 3 round-trips for the same result
subscribe_signals({nodePath: "/root/EventBus", signals: ["task_completed"]})
send_key_sequence({keys: ["1", "a", "o", "s"]})
get_signal_events()

// BAD: N round-trips instead of 1
send_key({key: "a"})
game_state()
send_key({key: "b"})
game_screenshot()

// BAD: shell sleeps between inputs — use {"wait": ms} checkpoints instead
send_input({action: "move_right"})
Bash("sleep 2")
send_input({action: "jump"})
game_screenshot()

Prefer structured checks over screenshots. game_state, evaluate_expression, and get_runtime_errors return text in milliseconds; a screenshot costs a viewport capture, a PNG write, and an image read. Reach for game_screenshot only when the visual result itself is what needs verifying (rendering, layout, animation).

When to use subscribe_signals instead: Only when you need to monitor signals across multiple separate commands (e.g., subscribe once, then issue several unrelated tool calls and check accumulated events later).

All configuration happens through environment variables in your MCP client config:

The server tries to auto-detect Godot in common install locations. If it can't find it, set GODOT_PATH explicitly.

Reduce token overhead and add safety by controlling which tools are exposed. All three filters can be combined:

• Toolsets — only expose specific categories: "MCP_TOOLSETS": "scene,node,script,analysis". Available: process, project, scene, node, animation, tilemap, resource, script, signal_group, uid, settings, interactive, screenshot, analysis, testing.
• Read-only mode — "MCP_READ_ONLY": "true" blocks every tool that creates, modifies, or deletes files or game state, leaving only readers like get_scene_tree, read_script, validate_scene, game_state, find_nodes.
• Exclusion — remove individual tools by name: "MCP_EXCLUDE_TOOLS": "export_project,manage_autoloads".

{
  "godot": {
    "command": "node",
    "args": ["/path/to/godot-mcp/build/index.js"],
    "env": {
      "GODOT_PATH": "/path/to/godot",
      "MCP_TOOLSETS": "scene,node,script,analysis",
      "MCP_READ_ONLY": "true"
    }
  }
}

MCP is an open standard. Any AI assistant that supports MCP can use this server:

The server speaks the stateless MCP 2026-07-28 protocol revision (built on MCP SDK v2): modern clients call tools directly with no initialize handshake, and the tool list ships cache hints so clients don't re-fetch it. Older 2025-era clients work too — the server auto-detects the client's protocol era per connection and serves the legacy handshake when needed.

Your local LLM (LlamaCPP)  -->  MCP Client (e.g., Cline)  -->  Godot MCP Server
   runs on localhost:8080        handles tool calls               controls Godot

llama-server -m your-model.gguf --port 8080

The server uses three execution strategies:

1. Direct CLI — Simple operations (launch editor, get version, read files) call Godot CLI commands or manipulate files directly from TypeScript.
2. Bundled GDScript — Complex scene operations use godot_operations.gd, a comprehensive script that runs via godot --headless --script to manipulate scene trees, nodes, and resources through the Godot API.
3. TCP Input Receiver — Interactive mode injects input_receiver.gd as a temporary autoload that listens on port 9876 for JSON commands (input injection, state queries, viewport capture).

pnpm install
pnpm run build
pnpm test           # run all tests (requires Godot installed)
pnpm lint           # eslint
pnpm format:check   # prettier
pnpm typecheck      # tsc --noEmit

CI runs all five checks on every push — please run them locally before opening a PR.

MIT — see LICENSE.