io.github.tomyud1/godot-mcp
MCP server for Godot game engine integration — control the Godot editor with AI
Open source Open in the app JSON README (API)
About
MCP server for Godot game engine integration — control the Godot editor with AI
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- tomyud1
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.6.0
- Stars
- 428
- Forks
- 48
- Open pull requests
- 3
- Last push
- 2026-08-24T06:08:33Z
- Repository state
- ativo
- Language
- GDScript
- License
- MIT
- Added
- 2026-08-29 04:01:33
- Updated
- 2026-08-29 04:01:33
- Origin id
io.github.tomyud1/godot-mcp
README
# Godot MCP
**Give your AI assistant full access to the Godot editor.**
Build games faster with Claude, Cursor, or any MCP-compatible AI — no copy-pasting, no context switching. AI reads, writes, and manipulates your scenes, scripts, nodes, and project settings directly.
> Godot 4.x · 75 tools · Undo/redo · Interactive project visualizer · MIT license
---
## Quick Start
### 0. Install Node.js (one-time setup)
Download and run the installer from **[nodejs.org](https://nodejs.org/en/download)** (LTS version). It's a standard installer — no terminal needed.
### 1. Install the Godot plugin
Inside the Godot editor, click the **AssetLib** tab at the top → search **"mcp"** → find **"Godot AI Assistant tools MCP"** → Install.
Then go to **Project → Project Settings → Plugins** and enable the **Godot MCP** plugin.
### 2. Add the server config to your AI client
**Claude Desktop** — Settings → Developer → Edit Config → open the config file and paste:
Mac / Linux:
```json
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
```
Windows:
```json
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-y", "godot-mcp-server"]
}
}
}
```
**Cursor** — Settings → MCP → Add Server:
Mac / Linux:
```json
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
```
Windows:
```json
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-y", "godot-mcp-server"]
}
}
}
```
**Claude Code** — run in terminal:
```bash
claude mcp add godot -- npx -y godot-mcp-server
```
Works with any MCP-compatible client (Cline, Windsurf, etc.)
### 3. Restart your AI client
Close and reopen Claude Desktop / Cursor / your client so it picks up the new config.
### 4. Restart your Godot project
Hit **Restart Project** in the Godot editor. Check the **top-right corner** — you should see **MCP Connected** in green. You're ready to go.
---
## What Can It Do?
### 42 Tools Across 6 Categories
| Category | Tools | Examples |
|----------|-------|---------|
| **File Operations** | 4 | Browse directories, read files, search project, create scripts |
| **Scene Operations** | 11 | Create scenes, add/remove/move nodes, set properties, attach scripts, assign collision shapes and textures |
| **Script Operations** | 6 | Apply code edits, validate syntax, rename/move files with reference updates |
| **Project Tools** | 14 | Run/stop scenes, query ClassDB, read errors from Output + Debugger, project settings, input map, collision layers, scene tree dumps, rescan filesystem |
| **Asset Generation** | 1 | Generate 2D sprites from SVG |
| **Visualization** | 6 | Interactive browser-based project map, scene graph explorer |
### Interactive Visualizer
Run `map_project` and get a browser-based explorer at `localhost:6510`:
- Force-directed graph of all scripts and their relationships
- Click any script to see variables, functions, signals, and connections
- Edit code directly in the visualizer — changes sync to Godot in real time
- Scene view with node property editing
- Find usages before refactoring
<img width="1710" height="1107" alt="image" src="https://github.com/user-attachments/assets/a9faf163-8b8b-43da-93ec-c7a651e8ac60" />
### Limitations
AI cannot create 100% of a game by itself — it struggles with complex UI layouts, compositing scenes, and some node property manipulation. It's still in active development, so feedback is very welcome!
---
## Architecture
```
┌─────────────┐ MCP (stdio) ┌──────────────┐ WebSocket ┌──────────────┐
│ AI Client │◄────────────────►│ MCP Server │◄─────────────►│ Godot Editor │
│ (Claude, │ │ (Node.js) │ port 6505 │ (Plugin) │
│ Cursor) │ │ │ │ │
└─────────────┘ │ Visualizer │ │ 42 tool │
│ HTTP :6510 │ │ handlers │
└──────┬───────┘ └──────────────┘
│
┌──────▼───────┐
│ Browser │
│ Visualizer │
└──────────────┘
```
---
## Current Limitations
- **Local only** — runs on localhost, no remote connections
- **One Godot editor at a time** — multiple AI clients can connect concurrently, but they all share a single Godot instance
- **Ctrl+Z does not reach AI changes** — the plugin writes to disk rather than the editor's live tree, so Godot's native undo has nothing to revert. Use the `mcp_undo` tool instead (ask the agent to undo).
- **AI is still limited in Godot knowledge** — it can't create 100% of the game alone, but it can help debug, write scripts, and tag along for the journey
---
## Development
To build from source instead of using npm:
```bash
cd mcp-server
npm install
npm run build
```
Then point your AI client at `mcp-server/dist/index.js` instead of using `npx`.
---
## Release notes
Narrative write-ups of each release live in [`release-notes/`](./release-notes/) (latest: [v0.6.0](./release-notes/v0.6.0.md)). For the full change history, see [`CHANGELOG.md`](./CHANGELOG.md).
---
## License
MIT
---
## Star History
<a href="https://www.star-history.com/?repos=tomyud1%2Fgodot-mcp&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=tomyud1/godot-mcp&type=date&legend=top-left" />
</picture>
</a>
---
**[npm package](https://www.npmjs.com/package/godot-mcp-server)** · **[Report Issues](https://github.com/tomyud1/godot-mcp/issues)**