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.

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.