# godot-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI agents like Claude Code run your Godot game, look at it, and play it.

Agents can already read and write `.gd` and `.tscn` files on their own. What they can't do is see what happens when the game runs. This closes that loop: start the game, take a screenshot, inspect the live scene tree, press inputs, read the errors.

## Tools

| Tool | What it does |
|---|---|
| `run_game` | Starts the project (or a specific scene) and waits until it is connected |
| `stop_game` | Stops the game |
| `get_logs` | Latest stdout/stderr lines: `print()` output, script errors, crashes |
| `screenshot_game` | Screenshot of the running game |
| `get_scene_tree` | Live node tree with types, scripts, positions and hidden nodes |
| `press_action` | Presses an Input Map action for a given time |

## How it works

```
agent  <--stdio-->  godot-mcp server  <--WebSocket-->  game (GodotMCP autoload)
                          |
                          +-- starts godot --path <project> as a child process
```

The server starts Godot itself and reads its output. When the game boots, the `GodotMCP` autoload connects back to the server over a WebSocket on `127.0.0.1` using a port and token passed on the command line. Without those arguments the autoload does nothing, and it is disabled in release builds.

## Requirements

- Godot 4 (tested on 4.7.2)
- Node.js 20 or newer

## Setup

1. Build the server:

   ```sh
   git clone https://github.com/CyberIce2077/godot-mcp.git ~/projects/godot-mcp
   cd ~/projects/godot-mcp
   npm install
   ```

2. Copy `addons/godot_mcp` into your game's `addons/` folder, then enable **Godot MCP** under Project > Project Settings > Plugins. Enabling it registers the `GodotMCP` autoload.

3. Add the server to Claude Code from your game's folder:

   ```sh
   claude mcp add godot -- node ~/projects/godot-mcp/dist/index.js
   ```

### Configuration

| Variable | Default | |
|---|---|---|
| `GODOT_PATH` | `godot` | Godot executable |
| `GODOT_PROJECT` | current directory | Folder containing `project.godot` |

For example:

```sh
claude mcp add godot -e GODOT_PROJECT=/path/to/game -e GODOT_PATH=/Applications/Godot.app/Contents/MacOS/Godot -- node ~/projects/godot-mcp/dist/index.js
```

## Limitations

- The game runs in a normal window. Godot's headless mode has no renderer, so screenshots would be blank.
- Only one game at a time per server.
- No editor integration yet: the agent edits scenes and scripts as files.

## License

MIT