convez.ai
MCP ServerAutomaçãoIntermediário
Erodenn

Godot MCP Runtime

Erodenn/godot-mcp-runtime

IA interage com Godot: edita, executa e verifica em tempo real

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP leve e sem footprint que permite assistentes de IA interagir com o Godot 4.x em tempo real. Combina edição headless (cenas, nós, scripts) com controle de runtime (screenshots, simulação de input, execução de GDScript), permitindo que agentes verifiquem suas próprias mudanças sem addon ou setup.

Instalação

$npx convez-ai Erodenn/godot-mcp-runtime

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
101
Forks
20
Acompanhando
5
Saúde
57%
Último commit
há 6 dias
Versão
v4.0.1
Issues abertas
0
Contribuidores
3

Casos de uso

  • Geração e validação automática de cenas de Godot via IA
  • Testes automatizados de gameplay e UI interativos
  • Desenvolvimento iterativo de jogos com feedback imediato para agentes

Veredito

Solução prática para automação de desenvolvimento em Godot. Destaca-se pela abordagem zero-footprint e capacidade de runtime que fecha o loop de verificação do código IA. Ideal para workflows onde agentes precisam validar próprias mudanças em tempo real.

README

A tradução para o português deste README ainda está na fila.

Godot MCP Runtime

A lightweight MCP server that pairs comprehensive headless editing with full runtime control over a Godot 4.x project. Scene, node, autoload, and validation ops cover everything short of the most niche corners of the engine; the runtime bridge adds screenshots, input simulation, UI discovery, and live GDScript against the running scene tree.

  • Headless editing — scenes, nodes, scripts, signals, validation, no editor window
  • Runtime control — screenshots, input simulation, UI discovery, and live GDScript against the running game
  • Zero footprint — no Godot addon, no project commits, auto-cleanup on shutdown

No addon required. Most Godot MCP servers that offer runtime support ship as a Godot addon, something you install into your project, commit to version control, and manage as a dependency. Use npx and there's no install or setup needed.

Think of it as Playwright MCP, but for Godot. This does the same thing for games: run the project, take a screenshot, simulate input, read what's on screen, execute a script against the live scene tree. The agent closes the loop on its own changes rather than handing off to you to verify.

[!NOTE] This is not a playtesting replacement. It doesn't catch the subtle feel issues that only a human notices, and it won't tell you if your game is fun. What it does is let an agent confirm that a scene loads, a button responds, a value updated, a script ran without errors. The ability to check work is crucial for AI driven workflows.

Contents

What It Does

Built for agents. Every tool is purpose-built and self-documenting. When something fails, the response tells the agent how to fix it; when something succeeds, it points toward the next step. The result is an AI that stays unstuck and self-corrects without needing you to nudge it along.

Headless editing. Create scenes, add nodes, set properties, attach scripts, connect signals, validate GDScript. All the standard operations, no editor window required.

Runtime bridge. When run_project or attach_project is called, the server injects McpBridge as an autoload. This opens a localhost-only TCP listener (both auto-select a free port when bridgePort is omitted; pass bridgePort to pin a specific port) and enables:

  • Screenshots: Capture the viewport — by default returns a 960x540 preview inline plus the full PNG on disk; use responseMode: 'full' for pixel-perfect or 'path_only' to skip the inline image
  • Input simulation: Batched sequences of key presses, mouse clicks, mouse motion, UI element clicks by name or path, Godot action events, and timed waits
  • UI discovery: Walk the live scene tree and collect every visible Control node with its position, type, text content, and disabled state
  • Live script execution: Compile and run arbitrary GDScript with full SceneTree access while the game is running

Background mode. Pass background: true to run_project and the Godot window moves off-screen (positioned at (-9999, -9999)) with physical input blocked: borderless, unfocusable, mouse-passthrough. Programmatic input, screenshots, and all runtime tools work exactly the same. Useful for automated agent-driven testing where the window shouldn't be visible or interactive.

Manual attach mode. When something other than MCP launches the game (a CI pipeline, an external debugger, your own shell), call attach_project first. It injects the bridge and marks the project active without spawning Godot, so when you launch the game manually, runtime tools work against it. Use detach_project when done.

[!IMPORTANT] get_debug_output is unavailable in attached mode. stdout and stderr only flow through processes MCP started itself, so when Godot is launched externally there's no captured output to return. Use run_project if you need the debug stream.

The bridge cleans itself up automatically when stop_project or detach_project is called. No leftover autoloads, no modified project files.

Quick Start

Prerequisites

That's it. No Godot addon, no project modifications.

Configure Your MCP Client

Add the following to your MCP client config. Works with Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.

Zero-install via npx (recommended):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

Or install globally:

npm install -g godot-mcp-runtime
{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

Or clone from source:

git clone https://github.com/Erodenn/godot-mcp-runtime.git
cd godot-mcp-runtime
npm install
npm run build
{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

[!TIP] Prefer pnpm? All three install paths work with pnpm. Substitute pnpm dlx godot-mcp-runtime for npx -y godot-mcp-runtime, pnpm add -g godot-mcp-runtime for the global install, or pnpm install && pnpm run build for the source build. pnpm ships stronger defaults against npm supply-chain attacks; see pnpm's supply chain security guide.

If Godot is on your PATH, you can omit GODOT_PATH entirely. The server will auto-detect it. Set "DEBUG": "true" in env for verbose logging.

[!IMPORTANT] Windows path gotchas. GODOT_PATH must point at the Godot executable itself, not its install folder. Backslashes in JSON must be escaped or replaced with forward slashes:

"GODOT_PATH": "D:\\Godot\\Godot_v4.4-stable_win64.exe"
// or equivalently
"GODOT_PATH": "D:/Godot/Godot_v4.4-stable_win64.exe"

Setting the variable from a wrapper .bat does not propagate to the MCP server — the path must live in the client's env block above.

Verify

Ask your AI assistant to call get_project_info. If it returns a Godot version string (e.g., 4.4.stable), you're connected and working.

Docs

Acknowledgments

Built on the foundation laid by Coding-Solo/godot-mcp for headless Godot operations.

Developed with Claude Code.

License

MIT

Ver o original no GitHub

Bom para

Relacionados