Content
# Godot Editor MCP (Model Context Protocol)
The MCP server built into the Godot Engine allows AI Agents (such as Claude Code) to access the features of the Godot editor through the standard MCP protocol.
## Easy Use
You can download the compiled engine from https://github.com/JzmStudio/GodotBuiltinMCP/releases/tag/engine.
1. Refer to the official documentation to compile the engine.
2. Start the compiled Godot engine in the `bin` directory.
3. The `.claude` folder and `.mcp.json` in this repository are already configured. Note that it will reference the `editor/mcp/godot-mcp.py` script, which can be downloaded separately. Claude Code can directly locate this folder for testing.
**This Godot engine is designed for convenient AI debugging and currently only supports reading editor error reporting. No modifications have been made to Godot except for MCP.**
## Features
- **Standard MCP Protocol**: Communicate with Claude Code via stdio mode or HTTP
- **Tool Invocation**: Support `ping` and `get_errors` tools
- **Error Detection**: Retrieve all error messages from the Errors panel at the bottom of the editor
- **Zero External Dependencies**: Implemented using Python standard libraries, no additional packages required
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
│ (MCP Host / Client) │
└─────────────────────────┬───────────────────────────────────┘
│ stdio (stdin/stdout)
▼
┌─────────────────────────────────────────────────────────────┐
│ godot-mcp.py │
│ (MCP Bridge) │
│ - JSON-RPC 2.0 stdio communication │
│ - HTTP forwarding to Godot Editor │
└─────────────────────────┬───────────────────────────────────┘
│ HTTP
▼
┌─────────────────────────────────────────────────────────────┐
│ Godot Editor │
│ (Embedded MCP Server) │
│ - TCP listening on 127.0.0.1:29170 │
│ - JSON-RPC 2.0 over HTTP │
└─────────────────────────────────────────────────────────────┘
```
## Prerequisites
- **Python**: 3.7 or higher
- **Godot Engine**: Compiled editor version supporting MCP
- **Claude Code**: Version supporting MCP stdio mode
## Quick Start
### 1. Configure Claude Code
Create or edit the `.mcp.json` file in the project root directory:
```json
{
"mcpServers": {
"godot-editor": {
"command": "python",
"args": ["editor/mcp/godot-mcp.py"],
"env": {
"GODOT_MCP_HOST": "127.0.0.1",
"GODOT_MCP_PORT": "29170"
}
}
}
}
```
**For Windows users**, if the `python` command is not available, try using `py` or `python3`:
```json
{
"mcpServers": {
"godot-editor": {
"command": "py",
"args": ["-3", "editor/mcp/godot-mcp.py"]
}
}
}
```
### 2. Start Godot Editor
Ensure the Godot Editor is compiled and running; the MCP server will automatically start on `127.0.0.1:29170`.
### 3. Restart Claude Code
After adding or modifying `.mcp.json`, restart Claude Code to make the configuration take effect.
## Available Tools
### ping
Test the connection to the Godot editor.
**Request Parameters**: None
**Response**:
```json
{"pong": true}
```
**Claude Code Example**:
```
Ask: "Test the Godot editor connection"
```
### get_errors
Retrieve all error messages from the Godot editor's Errors panel.
**Request Parameters**: None
**Response**:
```json
[
{
"message": "Parser Error: Unexpected token at line 10",
"type": "error",
"count": 1
}
]
```
**Claude Code Example**:
```
Ask: "What errors are in the Godot editor?"
Ask: "Get the Godot editor errors and help me fix them"
```
## Testing MCP Server
### Manually Testing HTTP Endpoint
```bash
curl -X POST http://localhost:29170/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"ping","params":{},"id":1}'
```
### Manually Testing stdio Bridge
```bash
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}' | python editor/mcp/godot-mcp.py
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' | python editor/mcp/godot-mcp.py
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_errors","arguments":{}},"id":3}' | python editor/mcp/godot-mcp.py
```
## Environment Variables
| Variable | Default Value | Description |
| ---------------------- | ------------- | --------------------------- |
| `GODOT_MCP_HOST` | `127.0.0.1` | Godot MCP server address |
| `GODOT_MCP_PORT` | `29170` | Godot MCP server port |
## Troubleshooting
### Claude Code Cannot Discover Tools
1. Confirm `.mcp.json` format is correct
2. Restart Claude Code
3. Check Python path is correct
### Connection Error
**Error**: `Cannot connect to Godot Editor at http://127.0.0.1:29170`
**Solution**:
- Confirm Godot Editor is running
- Confirm MCP server has started (check editor logs for `MCPServer: Started` message)
- Check port is not occupied
### curl Shows "transfer closed with N bytes remaining to read"
This is a Content-Length bug in older Godot versions. Ensure you are using the latest compiled editor.
## MCP Protocol Version
- Protocol Version: `2024-11-05`
- JSON-RPC Version: `2.0`
## File Structure
```
godot-engine/
├── editor/
│ └── mcp/
│ ├── mcp_server.cpp # Godot built-in MCP server
│ └── godot-mcp.py # stdio bridge script
└── .mcp.json # Claude Code MCP configuration
```
## Extension Plans
Potential tools to be added in the future:
- `get_warnings` - Get warnings list
- `get_console_messages` - Get console output
- `get_scene_tree` - Get scene tree structure
- `execute_script` - Execute GDScript code snippet
## Protocol Specification
This implementation follows the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) specification.
### Implemented Methods
| Method | Description |
| ----------------------------- | ------------------- |
| `initialize` | MCP handshake protocol |
| `tools/list` | List available tools |
| `tools/call` | Call specified tool |
| `notifications/initialized` | Handshake completion notification |
