godot-test-mcp

MCP server for automated Godot 4 game testing. Launch games, capture errors, verify changes — all from Claude Code or any MCP client.

Features (Phase 1)

• Launch & Stop: Run Godot projects in headless or windowed mode

• Error Capture: Parse and categorize GDScript errors, parse errors, resource failures

• One-Shot Verify: godot_run_and_check — launch, run N seconds, report PASS/FAIL

• Headless Import: Quick parse-check without running the game

Quick Start

1. Clone:

   git clone https://github.com/hyunlord/godot-test-mcp.git

2. Install:

   cd godot-test-mcp
   pip install -e .

3. Add to your Godot project's .mcp.json:

   {
     "mcpServers": {
       "godot-test": {
         "command": "python3",
         "args": ["/path/to/godot-test-mcp/src/server.py"],
         "env": {
           "GODOT_PROJECT_PATH": ".",
           "GODOT_PATH": ""
         }
       }
     }
   }

4. In Claude Code:

   godot_run_and_check(seconds=15)

Tools

Environment Variables

Godot Auto-Detection

If GODOT_PATH is not set, the server searches in order:

1. macOS: /Applications/Godot.app/Contents/MacOS/Godot, ~/Applications/...

2. Linux: /usr/bin/godot, snap/flatpak paths

3. Windows: C:\Godot\Godot.exe, %LOCALAPPDATA%\Godot\...

4. PATH lookup via which godot

Project Auto-Detection

If GODOT_PROJECT_PATH is not set, the server searches for project.godot starting from the current directory and walking up to 5 parent directories.

Roadmap

• Phase 1: Launch + error capture (current)

• Phase 2: Tick control + entity state query (WebSocket)

• Phase 3: Cheat commands + assertions

• Phase 4: Rust/GPU profiling

• Phase 5: CI/CD integration

License

MIT