# Godot MCP Documentation Server
**[中文文档](README_CN.md)** | English
A Model Context Protocol (MCP) server that provides AI assistants with access to the complete Godot Engine documentation, helping developers with Godot development by serving documentation directly to LLMs.
## Purpose
This server bridges the gap between AI assistants and Godot documentation, allowing developers to get instant, accurate answers about Godot classes, tutorials, and features without leaving their AI chat interface.
## Project Origin
This project is based on [godot-mcp-docs](https://github.com/Nihilantropy/godot-mcp-docs/tree/main?tab=readme-ov-file) by Nihilantropy, modified for local development on Windows without Docker.
## Installation
1. **Install uv** (if not already installed):
```powershell
# On Windows with PowerShell:
Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -UseBasicParsing | Invoke-Expression
```
2. **Clone the repository:**
```bash
git clone https://github.com/Nihilantropy/godot-mcp-docs.git
cd godot-mcp-docs
```
3. **Install Python dependencies:**
```bash
uv sync
```
This command reads from `pyproject.toml` and creates a virtual environment.
**Note**: `uv sync` uses `pyproject.toml` as the source of truth, not `requirements.txt`. This is the modern Python packaging standard (PEP 517/518/621). The `uv.lock` file ensures consistent dependency versions across environments.
## Setting Up Documentation
After installing dependencies, you need to download and process the Godot documentation:
1. **Generate documentation:**
```bash
uv run python .\docs_converter\godot_docs_converter.py
```
2. **Move docs folder to root:**
After conversion, move the generated `docs` folder to the project root directory.
3. **Generate documentation tree:**
```bash
cd docs
tree /f > docs_tree.txt
cd ..
```
**Note**: If you encounter Chinese encoding issues, use:
```powershell
tree /f | Out-File -Encoding utf8 docs_tree.txt
```
## Running the Server
Start the MCP server locally:
```bash
uv run python main.py
```
## Configuring MCP Client
### Claude Desktop Example
Add this to your Claude Desktop configuration file:
```json
{
"mcpServers": {
"godot-mcp-docs": {
"command": "uv",
"args": [
"run",
"python",
"main.py"
]
}
}
}
```
## Available Tools
- `get_documentation_tree()` - Get a tree-style overview of the entire documentation structure
- `get_documentation_file(file_path: str)` - Retrieve the content of specific documentation files
## Sample Usage
**Explore documentation structure:**
```
What documentation is available for Godot?
```
**Get specific class documentation:**
```
Show me the documentation for CharacterBody2D
```
**Learn about tutorials:**
```
What tutorials are available for 2D game development?
```
**Get specific tutorial content:**
```
Show me the first 2D game tutorial
```
**Compare classes:**
```
What's the difference between Node2D and CharacterBody2D?
```
## Debugging
### Option 1: FastMCP Dev UI (Recommended)
Start the server in dev mode:
```bash
uv run fastmcp dev main.py
```
Then open your browser to `http://127.0.0.1:8000` to see all tools and test them interactively.
### Option 2: MCP Inspector (Official Debugger)
Use Anthropic's official MCP Inspector:
```bash
npx @modelcontextprotocol/inspector uv run python main.py
```
This opens `http://localhost:5173` in your browser, showing all tools, request/response logs, and allowing manual tool testing. No need to run `uv run python main.py` separately.
### Option 3: HTTP API Debugging
Send JSON-RPC requests to the server:
```powershell
Invoke-WebRequest -Uri http://localhost:8000/message `
-Method POST `
-ContentType "application/json" `
-Body '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_documentation_file",
"arguments": {
"file_path": "classes/class_characterbody2d.md"
}
},
"id": 1
}'
```
Or using curl:
```bash
curl -X POST http://localhost:8000/message `
-H "Content-Type: application/json" `
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": { "name": "search_godot_docs", "arguments": { "query": "DisplayServer" } },
"id": 1
}'
```
## Understanding Path Resolution
The `DOCS_DIR = Path("docs").resolve()` in the code is relative to the **current working directory (CWD)** when you run Python, not the script location.
### Example
Assume your directory structure:
```
D:\Codes\16_MCP\ <-- 根目录
├── main.py <-- 启动脚本
├── docs\ <-- 文档目录
└── srcs\
└── util\
└── docs_utils.py <-- 工具代码 (里面写了 Path("docs"))
```
**Case A: Running from root directory**
```bash
cd D:\Codes\16_MCP
python main.py
```
- Current Working Directory: `D:\Codes\16_MCP`
- `Path("docs")` resolves to: `D:\Codes\16_MCP\docs` (Success)
**Case B: Running from subdirectory (common error)**
```bash
cd D:\Codes\16_MCP\srcs
python ../main.py
```
- Current Working Directory: `D:\Codes\16_MCP\srcs`
- `Path("docs")` resolves to: `D:\Codes\16_MCP\srcs\docs` (Fails - no docs folder)
### Best Practice
To ensure paths work regardless of where you run from, use `__file__`-based absolute positioning:
```python
from pathlib import Path
# Get current script directory
CURRENT_SCRIPT_DIR = Path(__file__).resolve().parent
# Navigate to project root
PROJECT_ROOT = CURRENT_SCRIPT_DIR.parent.parent
# Locate docs directory
DOCS_DIR = (PROJECT_ROOT / "docs").resolve()
```
## PowerShell Output Redirection Tips
### Save output to file:
- **Overwrite** (clears existing content):
```powershell
ls > list.txt
```
- **Append** (preserves existing content):
```powershell
ls >> list.txt
```
- **With UTF8 encoding** (recommended for Chinese):
```powershell
ls | Out-File -FilePath output.txt -Encoding utf8
```
- **See on screen and save**:
```powershell
ls | Tee-Object -FilePath log.txt
```
## Documentation Structure
The server provides access to the complete official Godot documentation with this structure:
```
docs/
├── _styleguides
├── _tools
│ └── redirects
├── about
├── classes
├── community
│ └── asset_library
├── contributing
│ ├── development
│ │ ├── compiling
│ │ ├── configuring_an_ide
│ │ ├── core_and_modules
│ │ ├── debugging
│ │ │ └── vulkan
│ │ ├── editor
│ │ └── file_formats
│ ├── documentation
│ └── workflow
├── getting_started
│ ├── first_2d_game
│ ├── first_3d_game
│ ├── introduction
│ └── step_by_step
├── img
└── tutorials
├── 2d
├── 3d
│ ├── global_illumination
│ ├── particles
│ └── procedural_geometry
├── animation
├── assets_pipeline
│ ├── escn_exporter
│ └── importing_3d_scenes
├── audio
├── best_practices
├── editor
├── export
├── i18n
├── inputs
├── io
├── math
├── migrating
├── navigation
├── networking
├── performance
│ └── vertex_animation
├── physics
│ └── interpolation
├── platform
│ ├── android
│ ├── ios
│ └── web
├── plugins
│ └── editor
├── rendering
├── scripting
│ ├── c_sharp
│ │ └── diagnostics
│ ├── cpp
│ ├── debug
│ ├── gdextension
│ └── gdscript
├── shaders
│ ├── shader_reference
│ └── your_first_shader
├── ui
└── xr
```
## Recommended System Prompt
For optimal results when working with Godot, use this system prompt:
> "When working with Godot game development questions, always search for the latest available documentation using the godot-mcp-docs tools. Start with `get_documentation_tree()` to understand the documentation structure, then use `get_documentation_file()` to retrieve specific information about classes, tutorials, or features. Prioritize official Godot documentation over general knowledge when providing Godot-related assistance."
## Updating Documentation
To update to a newer version of Godot documentation:
```bash
uv run python .\docs_converter\godot_docs_converter.py
cd docs
tree /f > docs_tree.txt
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
The Godot documentation content follows the original Godot documentation licensing:
- Documentation content (excluding `classes/` folder): [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
- Class reference files (`classes/` folder): MIT License
- Attribution: "Juan Linietsky, Ariel Manzur and the Godot community"
