@letsagents/godot-mcp

English | 中文

MCP server that gives AI clients runtime feedback from Godot — errors / scene tree / node properties / screenshots — so the AI can self-correct.

This package is the server half of Godot MCP Bridge. It bridges any MCP client (Claude Code, Cursor, Cline, Codex CLI, …) to the Godot editor's built-in debug protocol.

📦 This is the server only. The Godot editor plugin is a separate install — see Prerequisites.

Full docs, tool list, and architecture are in the main repository.

Install

npm install -g @letsagents/godot-mcp

Registers the godot-mcp command globally.

Prerequisites

1. Node.js ≥ 20 — to run the MCP server (@modelcontextprotocol/server v2 requires it).
2. Godot editor plugin — install it in your Godot project first: Godot editor → AssetLib → search "Godot MCP Bridge" → Install (or download the .zip from Releases and extract into addons/). Enable it in Project Settings → Plugins.
3. Godot editor running with the plugin enabled. The plugin opens a TCP bridge (default port 6510) that this server connects to.

Configure your MCP client

Standard MCP server over stdio. Set GODOT_MCP_BRIDGE_PORT to match the plugin's bridge port (default 6510).

Claude Code — project root .mcp.json:

{
  "mcpServers": {
    "godot-mcp": { "command": "godot-mcp", "env": { "GODOT_MCP_BRIDGE_PORT": "6510" } }
  }
}

Cursor (.cursor/mcp.json) and Cline (cline_mcp_settings.json) — identical JSON shape to the above.

Codex CLI (~/.codex/config.toml, TOML, stdio only):

[mcp_servers.godot-mcp]
command = "godot-mcp"
env = { GODOT_MCP_BRIDGE_PORT = "6510" }

Fallback (can't install globally): set command to "node" and add "args": ["/abs/path/to/server.js"].

How it works

MCP client ←stdio→ @letsagents/godot-mcp ←TCP:6510→ [Godot editor] bridge → running game

The server is a thin translator: MCP (stdio) on one side, a local TCP protocol to the in-editor bridge on the other. The bridge then uses Godot's debug protocol to talk to the running game. Zero intrusion on the user's project (one EditorPlugin, no manual autoload).

Environment variables

| Variable | Default | Purpose | |---|---|---| | GODOT_MCP_BRIDGE_PORT | 6510 | TCP port the plugin's bridge listens on. Must match on both sides. Set different ports per project (project.godot → [godot_mcp] bridge_port) to run multiple editors at once. |

Tools

41 tools — runtime feedback (get_runtime_errors / get_scene_tree / inspect_node / screenshot / …), interactive breakpoint debugging, editor-time asset queries, and efficiency controls. Full list + usage: docs/tools.md.

License

MIT © LuoHan