README.md
18 mega-tools for AI-assisted Godot 4.x game development
Better Godot MCP
Composite MCP server for Godot Engine -- 18 mega-tools for AI-assisted game development
Features
- 18 composite mega-tools -- scene, node, script, shader, animation, tilemap, physics, audio, navigation, UI, and more
- Full scene control -- create, parse, and modify
.tscnfiles directly without Godot running - GDScript CRUD -- create, read, write, and attach scripts in a single call
- Tiered token optimization -- compressed descriptions + on-demand
helptool
Quick Start
Claude Code Plugin (Recommended)
claude plugin add n24q02m/better-godot-mcp
MCP Server
Option 1: npx
{
"mcpServers": {
"better-godot": {
"command": "npx",
"args": ["-y", "@n24q02m/better-godot-mcp@latest"]
}
}
}
Other runners: bun x, pnpm dlx, yarn dlx also work.
Option 2: Docker
{
"mcpServers": {
"better-godot": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"n24q02m/better-godot-mcp:latest"
]
}
}
}
Note: Project path is passed via tool parameters (
project_path), not environment variables. In Docker mode, mount your project directory.
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 |
setup |
detect_godot, check |
Detect Godot binary and check project |
config |
status, set |
Server configuration |
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
| 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
Tools (6)
projectManage project metadata, run/stop, settings, and exports.scenesManage scene files including creation, listing, and modification.nodesManipulate nodes within the scene tree.scriptsPerform CRUD operations on GDScript files.shaderManage shader files with Godot 4 syntax support.physicsConfigure collision layers and physics bodies.Environment Variables
GODOT_PROJECT_PATHDefault project path for toolsGODOT_PATHPath to the Godot binaryConfiguration
claude_desktop_config.json
{"mcpServers": {"better-godot": {"command": "npx", "args": ["-y", "@n24q02m/better-godot-mcp@latest"]}}}Try it
→Create a new scene named 'Player' and add a CharacterBody2D node to it.
→List all GDScript files in my current project and read the contents of player.gd.
→Set up a new collision layer named 'Enemies' in my project physics settings.
→Add a new animation track to the existing AnimationPlayer in my main scene.