Skip to main content
Glama

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

Related MCP server: godot-devtool

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

Tool

Description

godot_launch

Start Godot (headless/windowed/editor)

godot_stop

Stop running Godot process

godot_get_errors

Get parsed errors/warnings

godot_get_output

Get raw stdout/stderr

godot_run_and_check

Launch → run N sec → collect errors → PASS/FAIL

godot_headless_import

Quick --headless --quit parse check

godot_get_status

Check if Godot is running/stopped/crashed

Environment Variables

Variable

Description

GODOT_PATH

Path to Godot executable (auto-detected if empty)

GODOT_PROJECT_PATH

Path to Godot project root (auto-detected if empty)

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.
      44
      4
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server for Godot Engine enabling AI to autonomously develop, test, and debug games with deterministic playtesting, multiplayer testing, DAP debugging, LSP integration, and token efficiency.
      31
      15
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that lets AI coding agents work on Godot 4 projects, including reading and editing scenes, writing and validating GDScript, running the game, and capturing screenshots.
      25
      18 npm
      MIT