git clone https://github.com/mikeumus/godot-mcp-rts.git
cd godot-mcp-rts
npm install      # also runs npm run build via the prepare hook

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp-rts/build/index.js"],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

get_scene_tree(
  projectPath: "/path/to/game",
  scenePath: "maps/test_map.tscn",
  includeProperties: true
)

create_script(
  projectPath: "/path/to/game",
  scriptPath: "scripts/my_unit.gd",
  extendsClass: "CharacterBody3D"
)

attach_script(
  projectPath: "/path/to/game",
  scenePath: "units/my_unit.tscn",
  nodePath: "MyUnit",
  scriptPath: "scripts/my_unit.gd"
)

set_node_property(
  projectPath: "/path/to/game",
  scenePath: "units/my_unit.tscn",
  nodePath: "MyUnit",
  properties: { visible: false, modulate.r: 0.5 }
)

test_run_scenario(
  projectPath: "/path/to/game",
  timeout: 30000
)

# 1. Start the game (must be running for IPC to work)
run_project(projectPath: "/path/to/game")

# 2. Wait a few seconds for it to render the first frame, then
test_take_screenshot(projectPath: "/path/to/game")
# → Screenshot saved to: /path/to/game/.mcp_screenshots/capture_<id>.png

# 3. Stop when done
stop_project()

MCP server                                       Running game
─────────────                                    ────────────
1. Write request.json     ──→   .mcp_screenshots/    ─→  TestController._process()
   { request_id, output_path? }                            polls every 6 frames

                                                        2. Detect request
                                                        3. get_viewport()
                                                            .get_texture()
                                                            .get_image()
                                                            .save_png(...)

4. Poll for response.json ←──   .mcp_screenshots/    ←─  Write response.json
   { request_id, status, absolute_path }                    Print TestController log

.mcp_screenshots/

npm run build         # always build first

npm test              # smoke + mutations (~35s, no game window)
npm run test:smoke    # ~3s   protocol handshake + tool registration
npm run test:mutations # ~30s every scene/script tool against a sandbox project
npm run test:screenshot # ~15s INTRUSIVE: opens a game window, opt-in

MCP_TEST_PROJECT_PATH=/path/to/your/game npm run test:screenshot

Claude Code / Cursor / etc.
       │
       │ MCP over stdio (SDK 1.x)
       ▼
godot-mcp-rts (Node/TypeScript)
       │
       ├──→ child_process → godot --headless --script godot_operations.gd <op> <json>
       │                    (most tools: scene mutation, script create, etc.)
       │
       ├──→ child_process → godot --headless --script test_operations.gd <op> <json>
       │                    (test harness tools: state snapshots, validation)
       │
       ├──→ child_process → godot <project> [--debug | --test-harness]
       │                    (run_project, test_run_scenario; long-running)
       │
       └──→ file-based IPC at <project>/.mcp_screenshots/request.json
                            (test_take_screenshot, polled by TestController)

npm run build        # compile TypeScript, copy .gd scripts to build/
npm run watch        # tsc --watch
npm run inspector    # launch the MCP inspector UI against the built server
npm test             # run the e2e suite (see Testing above)

godot-mcp-rts/
├── src/
│   ├── index.ts                      # MCP server, tool definitions, handlers
│   └── scripts/
│       ├── godot_operations.gd       # Headless GDScript dispatcher (file ops)
│       └── test_operations.gd        # Headless GDScript dispatcher (test harness)
├── tests/
│   └── e2e/
│       ├── _client.mjs               # JSON-RPC stdio client + tiny test runner
│       ├── smoke.mjs                 # Protocol + tool registration check
│       ├── mutations.mjs             # All scene/script tools, 20 assertions
│       ├── screenshot.mjs            # Live game capture via TestController IPC
│       └── README.md                 # How to run / extend the suite
├── scripts/
│   └── build.js                      # Post-tsc copy of .gd files into build/
├── build/                            # Compiled JS + copied scripts (gitignored)
├── README.md
├── CONTRIBUTING.md
├── LICENSE                           # MIT
├── package.json
└── tsconfig.json