better-godot-mcp

Integración de Godot Engine: 17 herramientas para desarrollo de juegos

GitHub

Documentación

Better Godot MCP

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

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

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-email-mcp	IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g...	MCP
better-notion-mcp	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
claude-plugins	Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...	Marketplace
imagine-mcp	Image and video understanding + generation for AI agents -- across Gemini, Op...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Shared foundation for building MCP servers -- Streamable HTTP transport, OAut...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
tacet	TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn...	Tooling
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP server for AI agents: web search, content extraction, and lib...	MCP

Features
Install
Smithery
Documentation
Tools
Comparison
Configuration
CLI
Security
Build from source
Trust model
License

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

Install

Runs over stdio by default. No credentials, no account, no relay -- the server reads and writes your local Godot project files directly. Godot 4.x is optional (only run/stop/export and editor actions need the binary).

Via npx (recommended)

npx -y @n24q02m/better-godot-mcp@latest

MCP client config

Add to your client's MCP config (Claude Code, Cursor, Windsurf, Codex, mcp.json):

{
  "mcpServers": {
    "better-godot-mcp": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "/path/to/your/godot/project"
      }
    }
  }
}

GODOT_PROJECT_PATH is optional -- every tool also accepts a project_path argument per call.

Via Docker

docker run -i --rm -v /path/to/your/godot/project:/project n24q02m/better-godot-mcp

The image is published for amd64 and arm64. Mount your project directory so the server can read and write scene, script, and resource files.

Smithery

better-godot-mcp ships a smithery.yaml so it can be discovered and deployed through Smithery. Smithery launches the server over stdio via npx -y @n24q02m/better-godot-mcp, and no configuration is required to start -- the server has no credentials and reads your local Godot project files directly.

Documentation

Full setup guide at mcp.n24q02m.com/servers/better-godot-mcp/setup/ -- install steps for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, and mcp.json.

Install with AI agent -- paste this to your AI coding agent:

Install MCP server better-godot-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-godot-mcp/setup-with-agent.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

Comparison

How better-godot-mcp stacks up against direct competitors in each pillar:

Capability	better-godot-mcp	Coding-Solo/godot-mcp	bradypp/godot-mcp	tugcantopaloglu/godot-mcp
Scene file management	Yes (`scenes`: create/list/info/delete/duplicate/set_main)	Yes (create/save)	Yes (create/save)	Yes (create/read/modify)
Node tree manipulation	Yes (`nodes`: add/remove/rename/list/get+set_property)	Partial (add only)	Yes (add/edit/remove)	Yes (add/remove/reparent)
GDScript file CRUD	Yes (`scripts`: create/read/write/attach/list/delete)	No	No	Partial (create from template + runtime eval)
Shader file CRUD	Yes (`shader`: create/read/write/get_params/list)	No	No	Partial (create/read .gdshader)
Animation authoring	Yes (`animation`: player/track/keyframe)	No	No	Yes (player/tween/state machine)
TileMap / TileSet	Yes (`tilemap`: tileset/source/set_tile/paint)	No	No	Yes (TileMapLayer cells)
Physics layers / bodies	Yes (`physics`: layers/collision/body_config)	No	No	Yes (collision/joints/raycast)
Audio bus management	Yes (`audio`: buses/effects/streams)	No	No	Yes (buses/routing/effects)
Navigation setup	Yes (`navigation`: region/agent/obstacle)	No	No	Yes (navigation)
UI control authoring	Yes (`ui`: control/theme/layout)	No	Partial (via add node)	Yes (controls/themes/menus)
Input map editing	Yes (`input_map`: action/event)	No	No	Yes (actions/key bindings)
Signal connections	Yes (`signals`: connect/disconnect/list)	No	No	Yes (connect/emit/await)
Launch editor / run project	Yes (`editor`, `project` run/stop)	Yes	Yes	Yes
Works without running editor	Yes (text-based `.tscn` parsing)	Yes (headless GDScript bridge)	Yes (headless GDScript bridge)	Partial (CLI headless or live TCP socket)
No credentials stored (TC-Local)	Yes	Yes	Yes	Yes
stdio + HTTP transports	Yes (stdio default + `--http`)	No (stdio only)	No (stdio only)	No (stdio only)
Docker image (amd64 + arm64)	Yes	No	No	No
Token-tiered tool descriptions	Yes (compact + on-demand `help`)	No	No	No

Configuration

The 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 the defaults.

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

HTTP transport

The server runs over stdio by default. To serve over Streamable HTTP instead, pass --http or set MCP_TRANSPORT=http (TRANSPORT_MODE=http is also accepted). HTTP mode exposes an unauthenticated /mcp endpoint -- there are no credentials to protect, so it is meant for trusted local or self-hosted use.

Variable	Required	Default	Description
`MCP_TRANSPORT`	No	`stdio`	Set to `http` for Streamable HTTP transport
`PORT`	No	`0` (auto-assign)	HTTP port (HTTP mode only)
`HOST`	No	Server default	HTTP host (HTTP mode only)

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)

CLI

The better-godot-mcp binary runs the MCP server by default (stdio; add --http for Streamable HTTP). It also exposes two diagnostic subcommands for checking your Godot environment before wiring up an MCP client.

Command	Description
`better-godot-mcp`	Start the MCP server (stdio default; `--http` for Streamable HTTP)
`better-godot-mcp detect`	Print the detected Godot binary as JSON (path, version, source); exits non-zero when none is found
`better-godot-mcp doctor`	Health-check the Godot binary and the current project (`GODOT_PROJECT_PATH`, else the working directory)

# Detect the Godot binary (JSON output)
npx -y @n24q02m/better-godot-mcp detect

{
  "found": true,
  "path": "/path/to/godot",
  "version": {
    "major": 4,
    "minor": 6,
    "patch": 3,
    "label": "stable.official",
    "raw": "4.6.3.stable.official"
  },
  "source": "system"
}

# Health-check the Godot binary and project
npx -y @n24q02m/better-godot-mcp doctor

[ok] godot binary: /path/to/godot (source: system)
[ok] godot version: 4.6.3.stable.official
[warn] project: no project.godot found at /path/to/cwd (set GODOT_PROJECT_PATH)

detect exits 1 when no Godot binary is found; doctor exits 1 when the binary is missing (a missing project.godot is only a warning).

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          # stdio mode (default)
bun run dev:http     # Streamable HTTP mode

Trust model

This plugin implements TC-Local (no auth required -- no credentials stored). See the trust model reference for full classification.

Mode	Storage	Encryption	Who can read your data?
stdio (default)	N/A (no credentials)	N/A	N/A
HTTP self-host	N/A (no credentials)	N/A	N/A

License

MIT -- See LICENSE.