godot-mcp-docs 1.0.0

MCP server that serves Godot documentation to LLM agents, version-aware, backed by godot-docs and godotengine/godot XML.

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_*).

Var	Purpose	Default (POSIX)	Default (Windows)
GODOT_MCP_REPO	Git URL to clone	https://github.com/Zei33/godot-mcp.git	(same)
GODOT_MCP_INSTALL_DIR	Destination	$HOME/.local/share/godot-mcp	%LOCALAPPDATA%\godot-mcp
GODOT_MCP_REF	Branch / tag	main	(same)
GODOT_MCP_NONINTERACTIVE	Skip the configurator	unset	unset

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.

Client	Global config	Project config	Shape
Claude Code	~/.claude.json	<project>/.mcp.json	mcpServers.godot-docs
Cursor	~/.cursor/mcp.json	<project>/.cursor/mcp.json	mcpServers.godot-docs
OpenAI Codex CLI [^1]	~/.codex/config.toml	(n/a — user-level only)	[mcp_servers.godot-docs]

[^1]: Codex CLI ships POSIX-only; the Windows configurator hides it.

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

Key	Purpose	Default
GODOT_DOCS_PATH	Path to your local godot-docs git clone	required
GODOT_DOCS_DEFAULT_VERSION	Fallback version when auto-detection fails	master
GODOT_MCP_CACHE_DIR	Where indexes + engine XML cache live	platform cache dir
GODOT_ENGINE_REPO_PATH	Local engine clone to use instead of fetching	unset
GODOT_MCP_OFFLINE	If 1, refuse network operations	0
GODOT_MCP_AUTO_FETCH	git fetch the docs repo on startup	1

Tools exposed

Tool	Purpose
get_class	Full class reference (inheritance, properties, methods, signals, constants, enums).
get_member	One property / method / signal / constant / enum value with full description.
list_members	Names + signatures for members of a given kind.
search_classes	BM25 search over class names and brief descriptions.
search_docs	BM25 search over prose docs (tutorials, guides).
get_page	Parsed prose page content, LLM-friendly.
list_toctree	Walk the toctree rooted at a given path.
resolve_ref	Resolve an RST :ref: label to a docs path.
resolve_redirect	Look up legacy URLs in _static/redirects.csv.
list_versions	Enumerate available docs branches and which are cached.
prepare_version	Warm the cache for a version ahead of time.

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.