Skip to main content
Glama
godot-mcp-omni
by Stankjedi

godot-mcp-omni

Codex-optimized MCP server for Godot 4.x. It is designed around a small number of high-signal manager tools rather than hundreds of narrow tools, while still exposing the full engine through dynamic Godot API dumps, headless GDScript operations, and an optional in-editor bridge.

Design goals

This edition is shaped for Codex-style agents that need a compact, reliable local control surface:

  • Zero npm runtime dependencies: pure Node.js 20+ JSON-RPC/MCP stdio implementation.

  • Small tool surface: 9 tools, each with clear action enums.

  • Full-engine reach without schema bloat: godot_docs can dump/search the current Godot binary's API, and godot_editor.rpc can call editor-bridge capabilities dynamically.

  • Codex-safe writes: all filesystem writes are project-root constrained; snapshots/backups are created before edits, and generated bridge tokens are ignored by git.

  • Hybrid control: headless Godot operations for CI/sandbox use; editor bridge for live selection, scene tree, inspector, logs, and viewport-related work.

  • Structured results: every tool returns content plus structuredContent, so models can parse outcomes reliably.

Related MCP server: Gear

Install

cd godot-mcp-omni
node src/index.js --doctor

Add to ~/.codex/config.toml:

[mcp_servers.godot]
command = "node"
args = ["/absolute/path/to/godot-mcp-omni/src/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 120
enabled = true

[mcp_servers.godot.env]
GODOT_PATH = "/absolute/path/to/Godot"
GODOT_MCP_SEARCH_DIRS = "/optional/folder/with/godot"
GODOT_MCP_HOST = "127.0.0.1"
GODOT_MCP_PORT = "8765"
GODOT_MCP_ALLOW_WRITE = "true"
GODOT_MCP_ALLOW_DANGEROUS = "false"

First Codex workflow

  1. Ask Codex: Use godot_meta doctor for my project at /path/to/MyGame.

  2. Ask Codex: Run godot_editor sync_addon and tell me how to enable the plugin.

  3. Open Godot, enable Godot Codex Bridge, then ask Codex: Connect to the Godot editor and read the scene tree.

  4. For headless work: Create a Player.tscn with CharacterBody2D root and add a CollisionShape2D child.

godot_editor sync_addon creates res://.godot_mcp_token when no GODOT_MCP_TOKEN is configured. The package and synced projects ignore that token file by default.

For newest Godot releases, prefer setting GODOT_PATH to the exact editor binary. If you keep multiple portable builds, set GODOT_MCP_SEARCH_DIRS to the folder that contains them; the server probes matching Godot binaries and chooses the newest detected version.

To install the latest official Godot 4.x stable editor for local validation or CI:

npm run godot:install-latest -- --out ./tmp/godot

The GitHub workflow in .github/workflows/latest-godot.yml runs on pushes, pull requests, and a daily schedule. It fetches the latest official Godot 4.x stable build dynamically and runs the live MCP test suite against it, so new stable releases are checked without editing repository code.

Tool surface

  • godot_meta: server info, doctor, tool help, Codex operating profile.

  • godot_project: project discovery, inspection, safe file read/write/edit/snapshot/diff.

  • godot_script: script listing, read/write, basic syntax checks.

  • godot_scene: create/read/validate scene files and run headless node operations.

  • godot_asset: resource scanning, import, UID lookup, folders.

  • godot_runtime: Godot version, run/stop/smoke/export/log capture.

  • godot_editor: sync/connect to editor bridge, inspect tree/selection, raw RPC.

  • godot_docs: dump/search the current Godot API.

  • godot_batch: run multi-step tool workflows with stop-on-error semantics.

See docs/ARCHITECTURE.md, docs/TOOLS.md, docs/SECURITY.md, and docs/MCP_ARCHITECTURE_REVIEW.md.

Available Tools

9 tools
godot_assetGodot Asset ManagerB
Destructive

Scan resources, import assets, resolve UIDs, and create project folders.

Inputs: action (required), path, limit, query, +3 more. Returns: ok, logs, meta, error, +6 more

godot_batchGodot Batch Workflow ManagerA
Destructive

Run a bounded sequence of other Godot MCP tool calls. Useful for Codex multi-step workflows and recovery loops.

Inputs: steps (required), dryRun, maxSteps, stopOnError. Returns: ok, logs, meta, error, +6 more

godot_docsGodot API Docs ManagerB

Dump/search the API of the currently configured Godot binary, including classes, methods, properties, and command-line help. dump_api writes an API cache under .godot_mcp/api.

Inputs: action (required), limit, query, withDocs, +5 more. Returns: ok, logs, meta, error, +6 more

godot_editorGodot Editor Bridge ManagerA
Destructive

Sync/connect to the in-editor bridge and perform live editor RPC: scene tree, selection, inspection, properties, and raw RPC.

Inputs: action (required), args, host, port, +10 more. Returns: ok, logs, meta, error, +6 more

godot_metaGodot MCP Meta ManagerA
Read-onlyIdempotent

Server info, doctor checks, tool help, and Codex usage profile. Start here.

Inputs: action (required), tool, toolAction, projectPath. Returns: ok, logs, meta, error, +6 more

godot_projectGodot Project ManagerB
Destructive

Discover, inspect, scan, read, and safely edit project-root files. Writes are constrained to the Godot project root.

Inputs: action (required), path, root, limit, +10 more. Returns: ok, logs, meta, error, +6 more

godot_runtimeGodot Runtime ManagerC
Destructive

Get Godot version, run/stop projects, smoke-test startup, collect logs, and export builds.

Inputs: action (required), args, scene, preset, +4 more. Returns: ok, logs, meta, error, +6 more

godot_sceneGodot Scene ManagerC
Destructive

Read scene text and perform headless scene creation/node operations through Godot.

Inputs: action (required), steps, nodeName, nodeType, +7 more. Returns: ok, logs, meta, error, +6 more

godot_scriptGodot Script ManagerC
Destructive

Read, write, list, and syntax-check GDScript/C# files.

Inputs: action (required), path, limit, query, +4 more. Returns: ok, logs, meta, error, +6 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Godot development (assets, batch, docs, editor, meta, project, runtime, scene, script) with clear, non-overlapping descriptions.

    Naming Consistency5/5

    All tools follow a consistent 'godot_<domain>' pattern, making it easy for agents to infer each tool's purpose from its name.

    Tool Count5/5

    With 9 tools, the scope is well-calibrated—comprehensive enough for full Godot workflows without being bloated or sparse.

    Completeness5/5

    The tool surface covers asset handling, project management, scene/script editing, runtime control, documentation, and editor integration, leaving no obvious gaps for typical Godot development tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.
      33
      21 npm
      3
      MIT