# Godot MCP

> Godot MCP is an open-source MCP server for developer tools. Let an agent run and playtest a Godot game with frozen game time and real input. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Repository:** https://github.com/satelliteoflove/godot-mcp
- **MCP Registry name:** io.github.satelliteoflove/godot-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [games and play](https://ai-powered.com/categories/games-and-play)
- **Listing updated:** 2026-11-18

## About

The server links an assistant to the Godot editor through a bridge addon over a local WebSocket on 127.0.0.1, and the addon reaches the running game via Godot's debugger protocol, so the game needs no extra ports. The goal is to let an agent verify its own changes rather than only edit nodes.

Playtesting is deterministic: freeze the game clock, step exact slices of game time or step until a condition holds, and send input in the window. Live state such as positions, velocities and animation state comes back as structured JSON, which often avoids paying for screenshots. Input covers named actions with analog strength, joypad, raw keys, mouse-look and text, and GDScript can be run inside the game to set up scenarios, such as jumping to wave 3.

The README counts 21 tools and 86 actions, split along read and write lines so read tools can be auto-allowed. They also cover scenes, nodes, animations, TileMap and GridMap cells, resources, 3D transforms, a profiler with spike detection, version-matched docs and mesh validation. It installs from npm, the addon is added with a command, and WSL2 is supported.

## Features

- **Frozen-time stepping:** Step the game clock by an exact amount or until a condition is true.
- **Live state as JSON:** Positions, velocities and custom data without screenshot costs.
- **Real input injection:** Actions, joypad sticks, keys, mouse-look and text typing.
- **Scenario setup:** Run GDScript inside the running game to prepare a test.
- **Editor and scene control:** Read and edit scenes, nodes, animations, TileMaps and GridMaps.
- **Profiler:** Frame time series with spike detection.

## Good for

- Reproduce a wall-clipping bug and inspect collision shapes
- Step to the second wave and list enemy positions
- Profile ten seconds of play for frame spikes
- Add a hit-flash animation to a player node

## Install

### Claude Code (Terminal)

```sh
claude mcp add godot-mcp -- npx -y @satelliteoflove/godot-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@satelliteoflove/godot-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@satelliteoflove/godot-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@satelliteoflove/godot-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@satelliteoflove/godot-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@satelliteoflove/godot-mcp"
      ]
    }
  }
}
```

## Tools

- `godot_scene`: Open and save scenes.
- `godot_node_read`: Inspect node properties and the scene tree.
- `godot_node_edit`: Update node properties and reparent nodes.
- `godot_editor_read`: Editor state, selection, screenshots and error log.
- `godot_editor_edit`: Run, stop and restart the game and control the 2D viewport.
- `godot_project`: Project info, settings and addon version checks.
- `godot_animation_read`: Query animations down to keyframes.
- `godot_animation_edit`: Author animation tracks and keyframes.
- `godot_tilemap_read`: Read TileMapLayer cells.
- `godot_tilemap_edit`: Edit TileMapLayer cells.
- `godot_gridmap_read`: Read GridMap cells.
- `godot_gridmap_edit`: Edit GridMap cells.
- `godot_resource`: Inspect resources such as SpriteFrames, TileSet and materials.
- `godot_scene3d`: Engine-computed 3D transforms, bounding boxes and visibility.
- `godot_docs`: Fetch Godot docs as markdown matched to the editor version.
- `godot_input`: Inject input into the running game.
- `godot_profiler`: Metric snapshots and frame time series.
- `godot_runtime_state`: Live game state as JSON digests and watch windows.
- `godot_game_time`: Freeze, step and step-until on the game clock.
- `godot_exec`: Run GDScript inside the running game.
- `godot_validate_meshes`: Detect corrupt procedural mesh data.

## FAQ

### How does it connect to Godot?

Through an editor addon over a local WebSocket, installed with the --install-addon command.

### What do I need?

Node.js and the Godot editor with the addon enabled under Project Settings, Plugins.

### Is WSL2 supported?

Yes, with auto-detection and a GODOT_HOST override.

### Can read tools be auto-allowed?

Yes. The tools split along read and write boundaries so writes stay gated.

### Is Godot MCP free?

Yes. Godot MCP is open source, so you can use and self-host it for free.

### How do I add Godot MCP to Claude Code?

Run this command in your terminal: claude mcp add godot-mcp -- npx -y @satelliteoflove/godot-mcp

### What are the best alternatives to Godot MCP?

The closest alternatives to Godot MCP are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/godot-mcp-3
