godot-mcp

An MCP server that gives AI coding agents (Claude Code, Cursor, OpenAI Codex, …) structured, version-aware access to the official Godot documentation.

Please don't bother the Godot maintainers about this

This is an unofficial, third-party project. It is not affiliated with, endorsed by, or supported by the Godot Engine project or its maintainers. Please do not file issues, ask questions, or request support about godot-mcp on godotengine/godot, godotengine/godot-docs, the Godot community channels, or to any Godot contributor. File issues on this repo instead.

Scope: this project supports using AI assistants for programming against Godot — GDScript, C#, engine APIs, editor scripting, shaders-as-code, etc. It does not endorse or facilitate using generative AI for art, audio, music, voice, writing, or other creative assets in your games. Use human-made (or properly licensed) creative work for those.

• Class reference — parsed from godotengine/godot's authoritative engine XML (doc/classes/*.xml).
• Prose docs — served from a user-maintained clone of godotengine/godot-docs.
• Version-aware — auto-detects the Godot version from your project's project.godot and serves docs from the matching branch. No manual branch switching required.
• External docs repo — the docs clone lives outside any individual game project, so game repos stay small.
• Non-invasive — per-version git worktrees mean your docs checkout's current branch is never modified.

Install

macOS / Linux

One-liner (clones the repo to ~/.local/share/godot-mcp, creates a venv, installs, and runs the interactive configurator):

curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.ps1 | iex

Installs to %LOCALAPPDATA%\godot-mcp by default. If you'd rather download the script first and inspect it before running, irm -OutFile install.ps1 <url> then .\install.ps1; you may need Set-ExecutionPolicy -Scope Process Bypass for the local invocation (the piped-to-iex form is unaffected).

Codex CLI has no Windows build, so the Windows configurator offers only Claude Code and Cursor.

Configurator

The configurator will:

1. Ask where your godot-docs clone lives (default ~/godot-docs, i.e. %USERPROFILE%\godot-docs on Windows). If it doesn't exist there, it offers to clone it for you.
2. Ask whether to install globally (all your projects) or for this project only.
3. Ask which AI clients to register with — any combination of Claude Code, Cursor, and (on POSIX) OpenAI Codex.
4. Write each client's config file (safe to re-run — it merges rather than overwrites).

Prerequisites

• git
• Python ≥ 3.10 (on Windows, either the python.org installer with "Add to PATH" enabled, or via py launcher)

Non-interactive install

curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/install.sh \
  | GODOT_MCP_NONINTERACTIVE=1 bash

# then, later:
~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/configure.py \
  --install-dir ~/.local/share/godot-mcp \
  --wrapper    ~/.local/share/godot-mcp/bin/godot-mcp \
  --docs-path  ~/godot-docs \
  --scope      global \
  --clients    claude,cursor,codex

# or, project-scoped:
~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/configure.py \
  --install-dir ~/.local/share/godot-mcp \
  --wrapper    ~/.local/share/godot-mcp/bin/godot-mcp \
  --docs-path  ~/godot-docs \
  --scope      project \
  --project-dir ~/games/my-game \
  --clients    claude,cursor

Install-script environment variables

These apply to both install.sh and install.ps1 (PowerShell reads them as $env:GODOT_MCP_*).

From PyPI (advanced)

If you'd rather manage the install yourself:

pipx install godot-mcp-docs   # or: pip install --user godot-mcp-docs

This gives you the godot-mcp command but skips the configurator — you'll need to register it with your MCP client manually (see Manual config below). You'll also need a local godot-docs clone and to set GODOT_DOCS_PATH yourself.

Supported clients

After install, restart the client — each should auto-discover the godot-docs MCP server.

Codex CLI has no per-project config, so it always installs globally even when you choose project scope (a note is printed so you know).

Manual config (if you'd rather skip the configurator)

Claude Code and Cursor both use this shape:

{
  "mcpServers": {
    "godot-docs": {
      "command": "/Users/you/.local/share/godot-mcp/bin/godot-mcp",
      "args": [],
      "env": {
        "GODOT_DOCS_PATH": "/Users/you/godot-docs"
      }
    }
  }
}

OpenAI Codex (~/.codex/config.toml):

[mcp_servers.godot-docs]
command = "/Users/you/.local/share/godot-mcp/bin/godot-mcp"
args = []

[mcp_servers.godot-docs.env]
GODOT_DOCS_PATH = "/Users/you/godot-docs"

Windows uses the same mcpServers shape — just point command at the .cmd wrapper (forward slashes work inside JSON strings, or escape backslashes as \\):

{
  "mcpServers": {
    "godot-docs": {
      "command": "C:/Users/you/AppData/Local/godot-mcp/bin/godot-mcp.cmd",
      "args": [],
      "env": {
        "GODOT_DOCS_PATH": "C:/Users/you/godot-docs"
      }
    }
  }
}

Version handling

When an MCP tool is called, the version served is chosen in this order:

1. Explicit version argument on the tool call.
2. The version written in the current working directory's project.godot (config/features = PackedStringArray("4.4", ...)).
3. GODOT_DOCS_DEFAULT_VERSION env var.
4. master.

If the resolved version has no matching docs branch, the server snaps to the closest lower branch (e.g. 4.4.1 → 4.4) and reports snapped: true so agents can surface a warning.

On startup, the server detects the project's Godot version from the client's working directory, pre-warms the matching docs worktree and FTS index, and logs:

godot-mcp: auto-detected Godot 4.4 → using docs branch '4.4' (project.godot)

Your working checkout of godot-docs stays on whatever branch you left it on — the server uses isolated per-version worktrees in its cache directory.

Environment variables

Tools exposed

Uninstall

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh | bash

Windows:

irm https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.ps1 | iex

Mirrors the installer: prompts which scope and clients to clean up, then optionally removes the install directory at ~/.local/share/godot-mcp. The uninstaller never touches your godot-docs checkout and never deletes the client config files — it only removes the godot-docs server entry from each.

Non-interactive:

# Remove from all global client configs, keep the install dir:
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh \
  | GODOT_MCP_NONINTERACTIVE=1 bash

# Remove everything including the install dir:
curl -fsSL https://raw.githubusercontent.com/Zei33/godot-mcp/main/uninstall.sh \
  | GODOT_MCP_NONINTERACTIVE=1 GODOT_MCP_DELETE_INSTALL=1 bash

Per-project uninstall:

~/.local/share/godot-mcp/.venv/bin/python \
  ~/.local/share/godot-mcp/scripts/unconfigure.py \
  --scope project --project-dir ~/games/my-game \
  --clients claude,cursor

Development

git clone https://github.com/Zei33/godot-mcp.git
cd godot-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pytest

License

MIT.