Godot MCP Server
# Godot MCP Server
MCP server that bridges Claude Code with the Godot editor via WebSocket. This repo only provides the MCP server — the Godot addon must be installed separately.
## Prerequisites
Install the Godot addon from:
**https://github.com/youichi-uda/godot-mcp-pro**
The addon connects automatically to the MCP server at `ws://localhost:6505` when the editor starts.
> **This repo is a free client for the premium addon [Godot MCP Pro](https://github.com/youichi-uda/godot-mcp-pro).**
> Get the premium version here:
> - [itch.io — Godot MCP Pro](https://y1uda.itch.io/godot-mcp-pro)
> - [Official site](https://godot-mcp.abyo.net/es/)
## Setup
**1. Clone this repo**
```bash
git clone https://github.com/neondeex/GodotMCP-Pro-Free-Client
cd GodotMCP-Pro-Free-Client
```
**2. Install dependencies**
```bash
npm install
```
**3. Start the server**
```bash
npm start
```
## Configure Claude Code
Add this to `~/.claude.json` under `mcpServers`:
```json
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/absolute/path/to/GodotMCP-Pro-Free-Client/index.js"]
}
}
}
```
Or via CLI:
```bash
claude mcp add godot node -- /absolute/path/to/GodotMCP-Pro-Free-Client/index.js
```
## Available Tools
**167 tools** across 25 categories:
| Category | Tools | Description |
|---|---|---|
| **Project** | 9 | Project info, filesystem, settings, autoloads |
| **Scene** | 9 | Create, open, save, list, play scenes |
| **Node** | 13 | Add, delete, move, rename, signals, properties |
| **Script** | 7 | List, read, create, edit, attach, validate GDScript |
| **Editor** | 13 | State, errors, screenshots, settings, EditorScript |
| **Input** | 5 | Simulate keyboard, mouse, actions, sequences |
| **Runtime** | 18 | Live game inspection, properties, signals, physics |
| **Animation** | 6 | List, create, delete animations and keyframes |
| **Animation Tree** | 8 | State machines, transitions, blend parameters |
| **Audio** | 6 | Buses, effects, volumes, AudioStreamPlayer |
| **Batch** | 7 | Multi-node operations, scene analysis |
| **Shader** | 6 | Create, read, edit shaders, assign materials |
| **Export** | 3 | List presets, export project, preset info |
| **Resource** | 4 | Read, edit, create, preview Godot resources |
| **Input Map** | 2 | Get and set input action bindings |
| **Scene 3D** | 6 | Meshes, lights, materials, camera, environment |
| **Physics** | 6 | Collision shapes, physics bodies, layers, raycast |
| **Analysis** | 6 | Unused resources, signal flow, dependencies, metrics |
| **Navigation** | 5 | NavRegion, NavAgent, bake mesh, layer config |
| **Particles** | 5 | Create particles, materials, presets, properties |
| **Profiling** | 2 | Performance monitors (game + editor) |
| **Testing** | 5 | Test scenarios, assertions, stress tests |
| **Theme** | 7 | Colors, fonts, styleboxes, apply to nodes |
| **Tilemap** | 6 | Set cells, fill rect, clear, get info |
| **Android** | 3 | List devices, deploy, preset info |
## How It Works
```
Claude Code ──(MCP/stdio)──▶ MCP Server ──(WebSocket :6505)──▶ Godot addon
```
1. Claude invokes a tool (e.g. `get_scene_tree`)
2. The MCP server forwards it as a JSON-RPC request to the Godot addon
3. Godot executes the command and returns the result
4. The MCP server relays the result back to Claude
The server tries ports 6505–6514 in order and binds to the first available one.
TDQS
Scored across 167 tools
The set spans many distinct Godot domains, but there are many parallel editor-vs-running-game variants and multiple performance/analysis tools with close boundaries (e.g., get_node_properties vs get_game_node_properties, get_game_performance vs get_performance_monitors vs get_editor_performance). Descriptions help clarify intent, but the sheer volume increases the chance of tool misselection.
Nearly all tools use snake_case and predictable verb/resource wording, which keeps names readable. However, some names lead with a domain/tool prefix (e.g., tilemap_set_cell, game_...) while others lead with the verb, so the pattern is not perfectly uniform.
167 tools is far beyond a reasonable MCP tool surface and is an extreme mismatch for practical tool selection, even for a broad Godot editor/runtime integration. The count creates significant cognitive overload and makes discovery and correct invocation difficult.
Coverage is very broad: filesystem, scenes, nodes, scripts, editor/runtime control, animation, audio, shaders, exports, resources, input, 3D/physics/navigation, particles, testing, themes, tilemaps, and Android deployment are all represented. Some lifecycle gaps remain, such as scene deletion/duplication, audio playback control, richer UI-control creation, and asset import workflows.