ARCHIVED 2026-09-13 — This repository is no longer maintained. Use the Godot editor + GDScript CLI toolchain instead of this MCP server. Existing installations keep working but receive no updates or support.
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 |
|---|
| agent-chat-plugin | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| better-drive | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| 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-semantic-release | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| better-workspace-mcp | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | 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 | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | 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 |
Table of contents
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 for file operations; only run/stop/export and editor actions need a Godot binary. The detector accepts Godot >=4.1. Live engine compatibility is currently verified with Godot 4.7.1 stable; this does not claim that every future minor release has been verified.
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
| 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 a Godot 4.x project structure; a Godot binary is optional for file operations
- 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) |
npx -y @n24q02m/better-godot-mcp detect
{
"found": true,
"path": "/path/to/godot",
"version": {
"major": 4,
"minor": 7,
"patch": 1,
"label": "stable.official",
"raw": "4.7.1.stable.official"
},
"source": "system"
}
npx -y @n24q02m/better-godot-mcp doctor
[ok] godot binary: /path/to/godot (source: system)
[ok] godot version: 4.7.1.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
bun run dev:http
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
Apache-2.0 -- See LICENSE.