godot-docs-mcp
by mcintalmo
README.md
# godot-docs-mcp
[](https://github.com/mcintalmo/godot-docs-mcp/actions/workflows/ci.yml)
[](https://github.com/mcintalmo/godot-docs-mcp/actions/workflows/build-index.yml)
An MCP server that serves the [Godot Engine](https://godotengine.org/) documentation to AI
coding agents.
Godot is under-represented in LLM training data relative to Unity and Unreal, so agents
routinely hallucinate GDScript APIs, invent node names, and apply Godot 3.x idioms to 4.x
projects. This server grounds them in the real docs: full-text search over the manual and
tutorials, plus a structured class reference built from the engine's own API metadata.
Built on MCP specification revision **2026-07-28** via the official
[`mcp`](https://github.com/modelcontextprotocol/python-sdk) Python SDK v2, which also serves
every earlier protocol revision from the same server.
> **Status: in development.** The server, its tools and resources, the command line, and
> the weekly workflow that publishes the index all work, and a prebuilt index for Godot 4.7
> is published, so `sync` installs one without a build. Not on PyPI yet — install from git,
> as below. Packaging as a Claude Code plugin, with skills, is a later phase.
## How it works
The documentation is indexed offline into a single SQLite database, so lookups are fast and
work without a network connection.
| Content | Source | Why |
| --- | --- | --- |
| Manual, tutorials, getting started | `godotengine/godot-docs` `.rst` | The authored prose |
| Class reference | `godotengine/godot` `doc/classes/*.xml` | Structured and typed — the `.rst` class pages are generated from these, so the XML gives exact signatures rather than prose |
`docs.godotengine.org` sits behind a Cloudflare challenge that rejects non-browser clients,
so the rendered site is not used as a source. Everything comes from GitHub.
## Getting started
Install the prebuilt index. It is one download of about 8 MB, and it only has to happen
once per Godot version.
```sh
uvx --from git+https://github.com/mcintalmo/godot-docs-mcp godot-docs-mcp sync
uvx --from git+https://github.com/mcintalmo/godot-docs-mcp godot-docs-mcp status
```
Then point a client at it. For Claude Code:
```sh
claude mcp add godot-docs -- \
uvx --from git+https://github.com/mcintalmo/godot-docs-mcp godot-docs-mcp
```
No index published for the version you want, or working on the parsers? Build one from
source instead. That needs `git` and takes about a minute:
```sh
uvx --from git+https://github.com/mcintalmo/godot-docs-mcp godot-docs-mcp sync --rebuild
```
Ask something a model reliably gets wrong — "what's the correct 4.x signature for
`move_and_slide`?" — and the answer should come back from `get_godot_class_member` as
`bool move_and_slide()`, with no arguments. It took several in Godot 3.x, which is what most
training data remembers.
## Commands
| Command | Purpose |
| --- | --- |
| `godot-docs-mcp` | Serve over stdio. This is what a client launches; `serve` is the default |
| `godot-docs-mcp sync` | Download a prebuilt index. `--rebuild` builds one from source instead |
| `godot-docs-mcp status` | What is indexed, what it was built from, and whether it has fallen behind. `--json` for a script |
| `godot-docs-mcp search "how do I make a character jump"` | Run a query through the same code the tools use, and print the ranking |
| `godot-docs-mcp package` | Write the release assets for the installed index. For the build workflow |
Every setting is also an environment variable, prefixed `GODOT_DOCS_MCP_` — see
[`config.py`](src/godot_docs_mcp/config.py) for the full table.
## Staying current
The documentation moves without warning, so two things track it independently.
A [weekly workflow](.github/workflows/build-index.yml) checks whether the upstream commits
have moved, and if they have, rebuilds the index, queries the whole corpus to confirm it
answers, and publishes it as a release asset. `godot-docs-mcp sync` is how that reaches you.
A running server checks once a day, in the background, whether a newer index has been
published. It never downloads one — an index that lags still answers correctly for the
version it was built from, and replacing it is your call. What it does instead is say so:
in `godot://status`, and as a one-line `notice` on search results. If the check cannot run,
the answer is "could not check", never "up to date".
## Tools
Every tool is read-only, and every response is capped so that one call cannot crowd out the
conversation it was meant to inform. A response that was cut says so, and names the call
that returns the rest.
| Tool | Purpose |
| --- | --- |
| `search_godot_docs` | Ranked search across the manual, tutorials, and class reference. Questions in plain words work |
| `fetch_godot_doc` | A page, or a single section of one |
| `get_godot_class` | Inheritance chain plus a signature map for a class — no prose, so a 300 KB class entry stays answerable |
| `get_godot_class_member` | Exact signature and full description for one member |
| `search_godot_code_examples` | GDScript and C# snippets, with the page and heading they came from |
## Resources
| URI | Content |
| --- | --- |
| `godot://status` | Indexed version, counts, and the upstream commits it was built from |
| `godot://index` | A map of the corpus: what it holds, how it is addressed, which tool to call |
| `godot://doc/{path}`, `godot://doc/{path}#{anchor}` | A page, or one section of it |
| `godot://class/{name}`, `godot://class/{name}#{member}` | A class, or one member of it |
The 515 pages and 1,078 classes are deliberately *not* enumerated in `resources/list`.
The templates are the URIs every tool already returns, so a search hit can be followed by
the host without a further tool call.
## Development
Requires [uv](https://docs.astral.sh/uv/).
```sh
uv sync --dev
uv run pre-commit install
```
| Command | Purpose |
| --- | --- |
| `uv run pytest` | Unit suite (hermetic — no network) |
| `uv run pytest -m slow` | Integration tests against a real index |
| `uv run ruff check --fix && uv run ruff format` | Lint and format |
| `uv run ty check` | Type check |
| `uv run pre-commit run --all-files` | Everything the CI lint job runs |
See [CLAUDE.md](CLAUDE.md) for the architecture and contribution conventions.
## License
MIT. The Godot documentation itself is licensed
[CC BY 4.0](https://github.com/godotengine/godot-docs/blob/master/LICENSE.txt) by Juan
Linietsky, Ariel Manzur and the Godot community; this project redistributes an indexed form
of it and does not alter that license.
TDQS
A4.7/5.0
Scored across 5 tools
Disambiguation5/5
Each tool targets a distinct retrieval need: prose pages, document/code search, class overviews, and individual member details. Cross-references are explicit, such as fetch_godot_doc directing class-reference lookups to get_godot_class, so an agent is unlikely to confuse them.
Naming Consistency5/5
All tool names use a lowercase snake_case verb_noun pattern: fetch/search/get followed by the object. The singular doc in fetch_godot_doc is meaningful because it fetches one page, while search_godot_docs searches the corpus, and get_godot_class_member extends get_godot_class naturally.
Tool Count5/5
Five tools cover the full Godot docs workflow without bloat: search prose/classes, fetch prose, get class summaries, get member details, and search code examples. Each tool has a distinct role and none is redundant.
Completeness5/5
The surface covers the main documentation workflows: discovering sources via search, retrieving prose pages section-by-section, extracting cheap class overviews, drilling into individual members, and finding runnable examples. Search hits carry the exact fields needed by the retrieval tools, so there are no dead ends.
Maintenance
ActivityMaintained
ResponsivenessNo issues