Godot Peek MCP

🚀 Godot Peek MCP

An MCP server for peeking into the Godot editor runtime. Run scenes, capture output, and inspect debugger state.

🚀 Quick Start

Why Another Godot MCP?

Other Godot MCPs wrap editor actions that LLMs can already perform. Claude can directly edit .tscn, .tres, and .gd files. It doesn't need a tool to "add a node" when it can simply edit the scene file.

This MCP focuses on runtime visibility: output panels, debugger state, and screenshots. These are the aspects that typically require interaction with the editor.

Setup

Download, copy, connect. Just three steps.

1. Download

Grab the release for your OS from Releases:

Extract it to a convenient location (e.g., ~/tools/godot-peek-mcp/). You'll obtain:

• godot-peek-mcp — the MCP server binary
• addons/godot_mcp/ — the Godot plugin

2. Install the Godot plugin

Copy the addons/godot_mcp folder into your Godot project, resulting in your-project/addons/godot_mcp/. Then enable it in Godot: Project > Project Settings > Plugins > Godot Peek MCP > Enable.

You should see something like this in the Output panel (the socket name is derived from your project directory):

GodotPeekPlugin: listening on /tmp/godot-peek-my-game.sock

3. Register the MCP server

Choose your MCP client:

claude mcp add godot-peek ~/tools/godot-peek-mcp/godot-peek-mcp

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

That's it. You're all set.

macOS: clearing quarantine

macOS may block unsigned binaries downloaded from the internet. If you receive a security warning, run:

xattr -cr ~/tools/godot-peek-mcp/godot-peek-mcp
xattr -cr ~/your-project/addons/godot_mcp/bin/

✨ Features

• Scene Control: Run main/current/specific scenes, stop the game
• Variable Overrides: Set autoload variables at startup (e.g., enable debug mode)
• Output Capture: Read the Output panel
• Debugger Integration: Errors, stack traces, local variables, performance monitors
• Debugger Control: Set breakpoints, step through code, pause/continue
• Runtime Inspection: Node tree and properties from running game
• Screenshots: Editor viewports or running game
• Expression Evaluation: Evaluate arbitrary GDScript in running game

📦 Installation

Tools

Scene Control

overrides: Set autoload variables at startup. Format: {"AutoloadName": {"property": value}} Example: {"DebugManager": {"debug_mode": true}}

Output & Debugging

Screenshots

Debugger Control

Note: Breakpoints only work with Godot's built-in script editor. If using an external editor, breakpoints won't trigger.

Expression Evaluation

Use this to query game state, set variables, or call methods without adding debug code.

💡 Usage Tips

Tips for LLM Users

• Iterative debugging: Run scene → check output → fix code → repeat. The run_* tools auto-detect startup crashes and return the stack trace.
• Test with overrides: Run with {"DebugManager": {"debug_mode": true}} to enable debug features without editing code.
• Inspect at runtime: Use get_remote_scene_tree to see what's instantiated, then get_remote_node_properties to check values.
• Auto-stop for testing: Use timeout_seconds to run briefly, then check get_output. Good for automated test loops.
• Screenshots for visual bugs: get_screenshot target=game shows exactly what the player sees.
• Evaluate expressions: Query any game state without print statements. evaluate_expression "get_tree().current_scene.name" or modify state: evaluate_expression "get_node('/root/Main/Player').set('health', 100)" (use .set() — assignment operators don't work in Expression class). Note: If the expression triggers a runtime error, the tool call will timeout since the game crashes before it can respond.

Exporting Your Game

The MCP plugin is editor-only. To export your game, exclude the extension files or the built game will error on startup:

Export > Resources > Filters to exclude: add addons/godot_mcp/bin/*, addons/godot_mcp/godot_peek.gdextension, addons/godot_mcp/plugin.*

The runtime helper script (peek_runtime_helper.gd) stays included since it's registered as an autoload, but it automatically skips initialization in export builds.

📚 Documentation

Notes

• Output reads from the Output panel: print(), push_error(), push_warning(), and editor messages.
• Debugger tools pull from the respective debugger tabs. frame_index selects which stack frame for locals (0=top). Important: get_debugger_stack_trace and get_debugger_locals only have data when the game is paused on a runtime error or breakpoint — calling them during normal execution returns empty results.
• Remote inspection (get_remote_scene_tree, get_remote_node_properties) only works while the game is running.
• Monitors (get_monitors) shows engine performance data: FPS, memory usage, draw calls, physics stats, etc.
• Screenshots save to /tmp/godot_peek_*.png. Editor screenshots capture active 2D/3D viewports. Game screenshots require the autoload that the plugin adds automatically.

Architecture

┌─────────────────────┐     stdio      ┌─────────────────────┐
│   Claude Code #1    │◄──────────────►│  Go MCP Server #1   │──┐
└─────────────────────┘                └─────────────────────┘  │
┌─────────────────────┐     stdio      ┌─────────────────────┐  │ Unix socket
│   Claude Code #2    │◄──────────────►│  Go MCP Server #2   │──┤ /tmp/godot-peek-<project>.sock
└─────────────────────┘                └─────────────────────┘  │
                                            ...                 │
                                       ┌────────────────────────▼┐
                                       │  C++ GDExtension        │
                                       │  (addons/godot_mcp)     │
                                       └────────────┬────────────┘
                                                    │ UDP (game features)
                                                    │ port 6971
                                       ┌────────────▼────────────┐
                                       │  Runtime Helper         │
                                       │  (running game)         │
                                       └─────────────────────────┘

Multiple MCP client sessions can connect simultaneously. Each session spawns its own Go MCP server process, and the C++ extension accepts all connections concurrently.

Requirements

• Godot 4.4, 4.5, or 4.6
• Linux x86_64 or macOS arm64 (Apple Silicon)

Building from Source

If you want to build from source instead of using a release:

# go mcp server
go build -ldflags="-s -w" -o godot-peek-mcp ./cmd/godot-peek-mcp

# c++ extension (requires godot-cpp — set GODOT_CPP_PATH or defaults to ~/Code/godot-cpp)
cd extension && scons platform=linux target=editor