Better Godot MCP

mcp-name: io.github.n24q02m/better-godot-mcp

Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game development

Features

• 17 composite mega-tools -- scene, node, script, shader, animation, tilemap, physics, audio, navigation, UI, and more
• Full scene control -- create, parse, and modify .tscn files directly without Godot running
• GDScript CRUD -- create, read, write, and attach scripts in a single call
• Tiered token optimization -- compressed descriptions + on-demand help tool

Setup

With AI Agent -- copy and send this to your AI agent:

Please set up @n24q02m/better-godot-mcp for me. Follow this guide: https://raw.githubusercontent.com/n24q02m/better-godot-mcp/main/docs/setup-with-agent.md

Manual Setup -- follow docs/setup-manual.md

Tools

| Tool | Actions | Description | |:-----|:--------|:------------| | project | info, version, run, stop, settings_get, settings_set, export | Project metadata, run/stop, and settings | | scenes | create, list, info, delete, duplicate, set_main | Scene file management | | nodes | add, remove, rename, list, set_property, get_property | Scene tree node manipulation | | scripts | create, read, write, attach, list, delete | GDScript file CRUD | | editor | launch, status | Launch Godot editor and check status | | config | status, set, detect_godot, check | Server configuration and environment detection | | resources | list, info, delete, import_config | Resource file management | | input_map | list, add_action, remove_action, add_event | Input action and event mapping | | signals | list, connect, disconnect | Signal connections | | animation | create_player, add_animation, add_track, add_keyframe, list | Animation players and tracks | | tilemap | create_tileset, add_source, set_tile, paint, list | TileMap and TileSet management | | shader | create, read, write, get_params, list | Shader file CRUD with Godot 4 syntax | | physics | layers, collision_setup, body_config, set_layer_name | Collision layers and physics bodies | | audio | list_buses, add_bus, add_effect, create_stream | Audio bus and effect management | | navigation | create_region, add_agent, add_obstacle | Navigation regions, agents, and obstacles | | ui | create_control, set_theme, layout, list_controls | UI control creation and theming | | help | - | Get full documentation for any tool |

Configuration

Godot binary is auto-detected from common install locations and PATH. No environment variables are required for basic usage. Optionally set GODOT_PROJECT_PATH and GODOT_PATH to override defaults.

| Variable | Required | Default | Description | |:---------|:---------|:--------|:------------| | GODOT_PROJECT_PATH | No | - | Default project path (tools also accept project_path param) | | GODOT_PATH | No | Auto-detected | Path to Godot binary |

Limitations

• Requires Godot 4.x project structure
• Scene files (.tscn) are parsed/modified via text manipulation, not Godot's internal API
• run/stop/export actions require Godot binary to be installed
• Docker mode has limited filesystem access (mount your project directory)

Security

• Binary detection -- Multi-path Godot detection (env, PATH, common locations)
• Project validation -- Verifies project.godot exists before operations
• Cross-platform -- Windows, macOS, Linux path handling

Build from Source

git clone https://github.com/n24q02m/better-godot-mcp.git
cd better-godot-mcp
bun install
bun run dev

License

MIT -- See LICENSE.