breakpoint-mcp

The MCP host for Breakpoint MCP — a Model Context Protocol server that exposes the Godot game engine to AI coding assistants across four planes: headless CLI, the live editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **276 tools

• 6 MCP resources**, built against the stable @modelcontextprotocol/sdk 1.x API. Developed and tested with Claude; because MCP is an open protocol, other clients can connect too (currently untested — reports welcome).

This package is the TypeScript host that Claude talks to over stdio. It needs the companion Godot editor addon (breakpoint_mcp) installed in your project to reach anything beyond the headless-CLI plane — see the repository for the addon and the full architecture.

Install

The fastest path — from your Godot project folder, one command installs and enables the editor addon (bundled in this package) and prints your MCP-client config:

npx breakpoint-mcp init

Then open the project in Godot and verify the setup:

npx breakpoint-mcp doctor

init copies the addon into addons/breakpoint_mcp/, enables it in project.godot, and prints — or, with --client claude-code|claude-desktop|cursor|windsurf|vscode, writes — the client config. By default it uses the addon bundled in this package; add --from-github [ref] to fetch the addon from GitHub instead (e.g. --from-github main). doctor checks the Godot binary, the addon, and the four bridges (add --require-live once the editor is open; --json for a machine-readable report).

To install the breakpoint-mcp command globally instead of invoking it via npx:

npm i -g breakpoint-mcp

Requires Node ≥ 18. The host targets the @modelcontextprotocol/sdk 1.x line (the registerTool({ inputSchema, outputSchema }) + elicitation surface).

Register with your MCP client

Claude is the primary, tested client. Claude Code:

claude mcp add godot -- npx -y breakpoint-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "breakpoint-mcp"],
      "env": {
        "GODOT_BIN": "/abs/path/to/Godot",
        "GODOT_PROJECT": "/abs/path/to/your/project"
      }
    }
  }
}

Set GODOT_BIN if godot isn't on your PATH. The full environment-variable table (bridge / LSP / DAP / runtime hosts, ports, and timeouts) and a complete walkthrough are in the repository README and the User Guide.

Using Cursor, VS Code, Windsurf, or another MCP client? The command is identical — see the Compatibility section for each client's config file and format.

The addon (required for the editor / runtime planes)

breakpoint-mcp init installs and enables this for you — the editor addon ships inside this package, so you don't need the repository to get it. To do it by hand instead, copy addons/breakpoint_mcp/ into your project and enable it under Project Settings → Plugins. Either way it opens the loopback servers this host connects to and auto-registers the in-game runtime bridge; without it, only the headless-CLI (godot_*) plane works.

Local-first

This bridge is a local co-development tool: all four planes talk to 127.0.0.1, and screenshots render real frames, so run the host on the same machine as Godot. A remote deployment can't see a local editor and is limited to the headless subset.

Security

The host spawns the Godot binary, can run GDScript and a configured local command, and writes files into your project; destructive tools are confirmation-gated. See the security policy for the trust model and how to report a vulnerability.

License

MIT — see LICENSE. Godot, Claude/Anthropic, and the named backend SDKs are trademarks of their respective owners; Breakpoint MCP is an independent project and is not affiliated with or endorsed by them.