# 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.