Skip to main content
Glama

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.

Related MCP server: godot-correctness-mcp

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.

Available Tools

20 tools
export_projectD

Exports project

Inputs: output (required), preset (required).

find_nodesD

Finds nodes in scene

Inputs: scene_path (required), type_filter, name_pattern.

format_gdscriptC

Formats GDScript

Inputs: script_path (required).

get_editor_selectionB

Gets current editor selection (requires open editor)

Inputs: no named parameters.

get_helpC

Gets Godot documentation

Inputs: search_term (required).

get_node_connectionsD

Gets node signals

Inputs: node_path (required), scene_path (required).

get_node_propertiesD

Gets node properties

Inputs: node_path (required), scene_path (required).

get_open_scenesB

Lists open scenes in editor (requires open editor)

Inputs: no named parameters.

get_project_settingsC

Parses project.godot

Inputs: prefix.

get_resource_dependenciesD

Gets resource deps

Inputs: resource_path (required).

get_resource_infoD

Gets detailed info about a resource

Inputs: resource_path (required).

inspect_scene_treeC

Returns node hierarchy

Inputs: scene_path (required).

list_export_presetsB

Returns export presets

Inputs: no named parameters.

list_resourcesC

Lists project resources

Inputs: type_filter.

resolve_pathC

Resolves a UID to a path or vice versa

Inputs: path_or_uid (required).

run_sceneC

Runs scene headlessly

Inputs: scene_path (required), timeout_ms.

run_testsB

Executes tests using GUT or a custom runner

Inputs: test_script.

validate_sceneC

Validates .tscn

Inputs: scene_path (required).

validate_scriptD

Validates .gd

Inputs: script_path (required).

verify_apiD

Checks Godot API

Inputs: class_name (required), method_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 20 tools

    Disambiguation4/5

    The tools are mostly distinct in purpose, covering different aspects like testing, scene inspection, resource management, and editor interactions. There is slight potential confusion between `inspect_scene_tree` and `find_nodes`, but they serve different goals (hierarchy vs. search). Overall, an agent can reliably select the right tool based on descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, such as `run_tests`, `get_project_settings`, `validate_script`, and `list_resources`. The verbs are action-oriented and the nouns clearly indicate the target resource. This makes the toolset predictable and easy to navigate.

    Tool Count3/5

    With 20 tools, this exceeds the typical 3-15 range, leaning toward the heavier side. However, each tool addresses a specific need in Godot development (testing, export, scene analysis, resource handling, editor access), so the count is justifiable albeit on the upper end. It feels slightly bloated but not excessive.

    Completeness4/5

    The toolset covers a broad range of Godot workflows, including project configuration, validation, running, formatting, scene/node introspection, resource management, and editor state. Missing features like creating or editing scenes/scripts are not core for an MCP that primarily aids analysis and execution. Minor gaps exist (e.g., no explicit node deletion), but agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Offline static correctness MCP server for Godot 4.x GDScript projects that lints code, looks up API symbols, and validates scenes/resources, all without a running editor.
      240 npm
      Creative Commons Attribution Non Commercial No Derivatives 4.0 International
    • A
      license
      B
      quality
      C
      maintenance
      Connects MCP-capable AI clients to a running Godot 4 editor for scene, node, project, and debug runtime operations via a local-first architecture.
      36
      1
      MIT