n24q02m/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

CI codecov npm Docker License: MIT

TypeScript Node.js Godot Engine semantic-release Renovate

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.