# Godot MCP Runtime

Gives an AI agent control of a Godot 4 project with no editor open, plus screenshots, simulated input and live GDScript against the running game. Useful when the agent has to check its own change instead of handing it back to you.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 95
- Author: Erodenn
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Erodenn/godot-mcp-runtime
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/mcp/godot-mcp-runtime

## What it does

The server runs through npx with no addon in your project. On `run_project` it drops in an autoload called `McpBridge`, which listens on localhost over TCP and exposes the tools: viewport capture (a 960x540 preview inline and the full PNG saved to disk by default), key presses and clicks, a walk of the live scene tree to list visible Control nodes, and arbitrary GDScript with SceneTree access. Launch with `profiling: true` and it also collects Godot's own profiler data and ranks GDScript functions by cost.

Editing needs no editor window: scenes, nodes, properties, script attachment, signals, GDScript checks. For quiet runs pass `background: true` and the window moves off-screen and stops taking physical input. When something else starts the game, be it a CI job or your shell, call `attach_project` first so the runtime tools work against that session.

One limit matters. `get_debug_output` returns nothing in attached mode, because stdout and stderr only reach the server from processes it spawned itself. Need the log stream? Go through `run_project`. The bridge tears itself down on `stop_project`, `detach_project`, game exit or a dropped client, and its files sit in `.mcp/godot-runtime/`, which the server adds to `.gitignore`. It will not replace a playtest: an agent can confirm a scene loads and a button answers, but it cannot tell you whether the game feels right.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GODOT_PATH`, `DEBUG`, `GODOT_MCP_DISABLE_ELICITATION`, `GODOT_MCP_STRICT`, `GODOT_MCP_DISABLE_SECURITY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Godot

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GODOT_PATH=<GODOT_PATH> --env DEBUG=<DEBUG> --env GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> --env GODOT_MCP_STRICT=<GODOT_MCP_STRICT> --env GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> --transport stdio godot-mcp-runtime -- npx -y godot-mcp-runtime
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add godot-mcp-runtime --env GODOT_PATH=<GODOT_PATH> --env DEBUG=<DEBUG> --env GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> --env GODOT_MCP_STRICT=<GODOT_MCP_STRICT> --env GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> -- npx -y godot-mcp-runtime
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "godot-mcp-runtime": {
            "command": "npx",
            "args": [
                "-y",
                "godot-mcp-runtime"
            ],
            "env": {
                "GODOT_PATH": "<GODOT_PATH>",
                "DEBUG": "<DEBUG>",
                "GODOT_MCP_DISABLE_ELICITATION": "<GODOT_MCP_DISABLE_ELICITATION>",
                "GODOT_MCP_STRICT": "<GODOT_MCP_STRICT>",
                "GODOT_MCP_DISABLE_SECURITY": "<GODOT_MCP_DISABLE_SECURITY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "godot-mcp-runtime": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "godot-mcp-runtime"
            ],
            "env": {
                "GODOT_PATH": "<GODOT_PATH>",
                "DEBUG": "<DEBUG>",
                "GODOT_MCP_DISABLE_ELICITATION": "<GODOT_MCP_DISABLE_ELICITATION>",
                "GODOT_MCP_STRICT": "<GODOT_MCP_STRICT>",
                "GODOT_MCP_DISABLE_SECURITY": "<GODOT_MCP_DISABLE_SECURITY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GODOT_PATH=<GODOT_PATH> -e DEBUG=<DEBUG> -e GODOT_MCP_DISABLE_ELICITATION=<GODOT_MCP_DISABLE_ELICITATION> -e GODOT_MCP_STRICT=<GODOT_MCP_STRICT> -e GODOT_MCP_DISABLE_SECURITY=<GODOT_MCP_DISABLE_SECURITY> godot-mcp-runtime npx -y godot-mcp-runtime
```
Replace <…> with your own values

## When to use it
- confirm a scene loads without errors
- grab a viewport screenshot from a running game
- fire clicks and key presses at the UI and see what changed
- run GDScript against the live scene tree
- rank the most expensive GDScript functions with the profiler

## Example prompts
- Run the Godot project in the background and screenshot the main menu
- Click the Start button through input simulation and show what changed on screen
- Attach to the game I already launched with `attach_project` and run a scene-tree script

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25085
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4523
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1348
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1219
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 975
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 733

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md