Godot MCP Server

godot-mcp lets MCP clients inspect, validate, test, export, and query Godot projects. It supports headless Godot commands and, optionally, live state from an open Godot editor.

Requirements

• Node.js 18 or newer
• Godot 4.1 or newer, installed locally
• A Godot project containing project.godot

The live-editor tools additionally require the MCP Bridge addon described below. The remaining tools run headlessly.

Install

From a local checkout

npm install
npm run build

From npm (after publication)

npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot

Configure an MCP client

Always provide the project path. MCP desktop clients usually start servers in their own working directory, so automatic project discovery alone is not reliable.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

The equivalent command-line options are:

godot-mcp --project /path/to/godot-project --godot /path/to/godot

GODOT_PATH/--godot is optional only when the godot executable is already on PATH. On Windows, a _console.exe executable is preferred.

Enable live editor tools

1. Copy godot-plugin/addons/mcp_bridge to <your-project>/addons/mcp_bridge.
2. In Godot, open Project > Project Settings > Plugins and enable MCP Bridge.
3. Keep the Godot editor open while using live tools.

The bridge listens on 127.0.0.1:7000 by default. Set mcp/plugin/port in project.godot to override it; the server reads that setting from the project configured above. Exclude addons/mcp_bridge/* from production export presets.

Tools

• Project and export: get_project_settings, list_export_presets, export_project
• Tests and validation: run_tests, validate_scene, validate_script, run_scene, format_gdscript
• Scenes and resources: inspect_scene_tree, find_nodes, get_node_properties, get_node_connections, list_resources, get_resource_dependencies, resolve_path, get_resource_info
• Documentation: verify_api, get_help
• Live editor: get_editor_selection, get_open_scenes

Most tools return a structured JSON result with success, data, errors, warnings, and timing metadata.

Development and verification

npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published

GitHub Actions runs both the Node/MCP tests and Godot-addon checks on pushes and pull requests.

Release checklist

1. Update the version in package.json.
2. Run npm test, npm run test:godot, and npm pack --dry-run.
3. Publish with npm publish and create a matching GitHub release.

License

This project is licensed under the MIT License.