# 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

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

Add to `~/.codex/config.toml`:

```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:

```sh
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`.