io.github.tomyud1/godot-mcp
MCP server for Godot game engine integration โ control the Godot editor with AI
Ask AI about io.github.tomyud1/godot-mcp
Powered by Claude ยท Grounded in docs
I know everything about io.github.tomyud1/godot-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 ยท 42 tools ยท Interactive project visualizer ยท MIT license
Quick Start
0. Install Node.js (one-time setup)
Download and run the installer from nodejs.org (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:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Windows:
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-y", "godot-mcp-server"]
}
}
}
Cursor โ Settings โ MCP โ Add Server:
Mac / Linux:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "godot-mcp-server"]
}
}
}
Windows:
{
"mcpServers": {
"godot": {
"command": "cmd",
"args": ["/c", "npx", "-y", "godot-mcp-server"]
}
}
}
Claude Code โ run in terminal:
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
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
- Single connection โ one Godot instance at a time
- No undo โ changes save directly (use version control)
- 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:
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/ (starting with v0.5.0). For the full change history, see CHANGELOG.md.
License
MIT
