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:

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.
Ask whether to install globally (all your projects) or for this project only.
Ask which AI clients to register with — any combination of Claude Code, Cursor, and (on POSIX) OpenAI Codex.
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 ¹	`~/.codex/config.toml`	(n/a — user-level only)	`[mcp_servers.godot-docs]`

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:

Explicit version argument on the tool call.
The version written in the current working directory's project.godot (config/features = PackedStringArray("4.4", ...)).
GODOT_DOCS_DEFAULT_VERSION env var.
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.

Codex CLI ships POSIX-only; the Windows configurator hides it. ↩

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
scripts		scripts
src/godot_mcp		src/godot_mcp
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
pyproject.toml		pyproject.toml
uninstall.ps1		uninstall.ps1
uninstall.sh		uninstall.sh

Navigation Menu

Repository navigation

About

Repository files navigation

godot-mcp

Please don't bother the Godot maintainers about this

Install

macOS / Linux

Windows (PowerShell)

Configurator

Prerequisites

Non-interactive install

Install-script environment variables

From PyPI (advanced)

Supported clients

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

Version handling

Environment variables

Tools exposed

Uninstall

Development

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

godot-mcp

Please don't bother the Godot maintainers about this

Install

macOS / Linux

Windows (PowerShell)

Configurator

Prerequisites

Non-interactive install

Install-script environment variables

From PyPI (advanced)

Supported clients

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

Version handling

Environment variables

Tools exposed

Uninstall

Development

License

Footnotes

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages