Better Godot MCP

Name: better-godot-mcp
Author: n24q02m

Composite MCP Server for Godot Engine - Optimized for AI Agents

codecov npm Docker License: MIT

TypeScript Node.js Godot Engine semantic-release Renovate

Why "Better"?

18 composite tools that consolidate Godot Engine operations into action-based mega-tools optimized for AI agents.

Key Features

Feature	Description
Composite Actions	1 tool call instead of multiple steps
Full Scene Control	Create, parse, modify `.tscn` files directly
GDScript CRUD	Create, read, write, attach scripts
Shader Support	Create, edit shaders with Godot 4 syntax
Input Mapping	Manage input actions and events
Physics/Audio/Nav	Configure collision layers, audio buses, navigation
Token Efficient	Tiered descriptions with on-demand `help` tool

Quick Start

Option 1: Package Manager (Recommended)

{
  "mcpServers": {
    "better-godot": {
      "command": "bun",
      "args": ["x", "@n24q02m/better-godot-mcp@latest"]
    }
  }
}

Alternatively, you can use npx, pnpm dlx, or yarn dlx:

Runner	`command`	`args`
npx	`npx`	`["-y", "@n24q02m/better-godot-mcp@latest"]`
pnpm	`pnpm`	`["dlx", "@n24q02m/better-godot-mcp@latest"]`
yarn	`yarn`	`["dlx", "@n24q02m/better-godot-mcp@latest"]`

Option 2: Docker

{
  "mcpServers": {
    "better-godot": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--name", "mcp-godot",
        "n24q02m/better-godot-mcp:latest"
      ]
    }
  }
}

Note: Project path is passed via tool parameters (project_path), not environment variables.

Tools

Tool	Actions
`project`	info, version, run, stop, settings_get, settings_set, export
`scenes`	create, list, info, delete, duplicate, set_main
`nodes`	add, remove, rename, list, set_property, get_property
`scripts`	create, read, write, attach, list, delete
`editor`	launch, status
`setup`	detect_godot, check
`config`	status, set
`help`	Get full documentation for any tool
`resources`	list, info, delete, import_config
`input_map`	list, add_action, remove_action, add_event
`signals`	list, connect, disconnect
`animation`	create_player, add_animation, add_track, add_keyframe, list
`tilemap`	create_tileset, add_source, set_tile, paint, list
`shader`	create, read, write, get_params, list
`physics`	layers, collision_setup, body_config, set_layer_name
`audio`	list_buses, add_bus, add_effect, create_stream
`navigation`	create_region, add_agent, add_obstacle
`ui`	create_control, set_theme, layout, list_controls

Token Optimization

Tiered descriptions for efficient token usage:

Tier	Purpose	When
Tier 1	Compressed descriptions	Always loaded
Tier 2	Full docs via `help` tool	On-demand

{"name": "help", "tool_name": "scenes"}

Environment Variables

Variable	Required	Description
`GODOT_PROJECT_PATH`	No	Default project path (most tools accept `project_path` param)
`GODOT_PATH`	No	Path to Godot binary (auto-detected if not set)

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)

Build from Source

git clone https://github.com/n24q02m/better-godot-mcp
cd better-godot-mcp
mise run setup
bun run build

Requirements: Node.js 24+, bun latest

Compatible With

Claude Desktop Claude Code Cursor VS Code Copilot Antigravity Gemini CLI OpenAI Codex OpenCode

Also by n24q02m

Server	Description	Install
better-notion-mcp	Notion API for AI agents	`npx -y @n24q02m/better-notion-mcp@latest`
wet-mcp	Web search, content extraction, library docs	`uvx --python 3.13 wet-mcp@latest`
mnemo-mcp	Persistent AI memory with hybrid search	`uvx mnemo-mcp@latest`
better-email-mcp	Email (IMAP/SMTP) for AI agents	`npx -y @n24q02m/better-email-mcp@latest`

Contributing

See CONTRIBUTING.md

License

MIT - See LICENSE

better-godot-mcp