Godot MCP Bridge

Custom MCP server that lets an MCP client (VS Code, Claude, Cursor, etc.) call commands in a Godot project through a local WebSocket bridge.

Stack

• TypeScript MCP server over stdio

• @modelcontextprotocol/sdk (official TypeScript SDK)

• ws for the Godot bridge connection

Current parity status

• Tool-surface compatibility: 163 tools are registered with names aligned to Godot MCP Pro categories.

• Runtime behavior: core tool set is implemented in the included Godot bridge script.

• Remaining tools: routed and recognized, but will return structured "not implemented" errors until handler logic is added.

This means command names are already compatible, but full behavioral parity is still in progress.

Quick setup (recommended)

1. Clone this repository inside your Godot project folder.

2. Run:

npm install
npm run run

npm run run will automatically:

• Build the MCP server (dist/index.js)

• Detect project.godot in parent folders (or GODOT_PROJECT_PATH)

• Sync bridge script to addons/godot_mcp_server/mcp_bridge.gd

• Ensure [autoload] entry (McpBridge) in project.godot

• Create/update .mcp.json entry godot-mcp-server-local

• Create/update agent context files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md)

• Create/update .cursorignore to reduce unnecessary scanning on this MCP server folder

Manual setup

npm install
npm run build

Run

npm run setup
npm run start

For development:

npm run dev

Godot setup

If you use npm run run or npm start, Godot setup is automatic.

Manual fallback:

1. Copy godot/autoload/mcp_bridge.gd into your Godot project.

2. Add it as an AutoLoad singleton in Godot (Project > Project Settings > AutoLoad).

3. Keep port at 6505 unless you customize both sides.

4. Open the project so the bridge starts and listens on WebSocket.

MCP config

The workspace includes .vscode/mcp.json configured to run:

• command: node

• args: dist/index.js

Build before using the MCP config:

npm run build

How to use from MCP client

1. Run npm run build.

2. Start MCP client with this server (dist/index.js).

3. Call godot_connect.

4. Call tool(s), for example:

   • get_project_info

   • get_scene_tree

   • search_files

   • add_node

   • update_property

If a tool is not implemented yet on the Godot side, you will get a structured error with suggestion.

Core control tools

• godot_connect: connects to the WebSocket bridge

• godot_status: returns connection details

• godot_command: sends { command, payload } to Godot and returns the result

• godot_disconnect: disconnects the bridge

Implemented handlers in mcp_bridge.gd

• Bridge and diagnostics: ping, editor_info, get_project_info, get_output_log, clear_output

• Files and scripts: get_filesystem_tree, search_files, list_scripts, read_script, create_script, edit_script, search_in_files

• Scene and nodes: get_scene_tree, get_scene_file_content, create_scene, delete_scene, save_scene, add_node, delete_node, rename_node, move_node, duplicate_node, update_property, get_node_properties

• Aliases for compatibility: get_game_scene_tree, get_game_node_properties, set_game_node_property, set_game_node_properties, read_shader, edit_shader, open_scene

Compatibility catalog

The server registers 163 Pro-style tool names across categories:

• Project

• Scene

• Node

• Script

• Editor

• Input

• Runtime

• Animation

• TileMap

• Theme/UI

• Profiling

• Batch/Refactor

• Shader

• Export

• Resource

• Physics

• 3D Scene

• Particles

• Navigation

• Audio

• AnimationTree

• State Machine

• Blend Tree

• Analysis

• Testing/QA

Godot bridge protocol (JSON-RPC style)

The server connects to ws://127.0.0.1:6505 by default and supports local port scan 6505-6509 unless disabled.

Request shape sent to Godot:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_project_info",
  "params": {}
}

Response shape expected from Godot:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ok": true
  }
}

Or an error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Tool not implemented",
    "data": {
      "suggestion": "Use implemented core tools first"
    }
  }
}

Override bridge URL with environment variable:

GODOT_WS_URL=ws://127.0.0.1:6505 npm run dev

References

• MCP organization: https://github.com/modelcontextprotocol

• TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

• MCP docs: https://modelcontextprotocol.io/docs