godot-mcp-server

An MCP server that gives AI coding agents first-class access to the Godot game engine: project inspection, project.godot editing, scene/script parsing, headless exports, running games with live control (eval, scene-tree inspection, hot reload and screenshots), and version-accurate API documentation search.

It targets Godot 4.7 and works without the editor open — agents drive Godot through its command line and a small in-game bridge. An optional desktop app manages the server and wires it into your AI agents in one click.

This is the Godot counterpart to defold-mcp, built with the same architecture.

---

Contents

• Features
• Requirements
• Install
• Configuration
• Tools
• The live-control bridge
• Desktop app
• Architecture
• Development
• License

Features

• Project parsing — turn project.godot, .tscn/.tres scenes and .gd/.cs scripts into structured JSON (node trees, signals, exports, connections, outlines).
• Toolchain management — resolve the project's target version, download and cache the matching editor binary and export templates, or use a binary you already have (GODOT_BIN).
• Build pipeline — headless import (compile check), multi-mode exports (release/debug/pack) from your presets, clean, and a doctor diagnostic.
• Runtime control — launch games as child processes, stream logs, stop them, and (with the bridge) inspect the live scene tree, evaluate expressions, set node properties, hot-reload scripts, and capture screenshots.
• API docs — search and read the Godot class reference for the exact engine version in use (generated locally via --doctool, with a GitHub fallback).
• Two transports — stdio (default) or HTTP, so multiple agents can share one server.
• Desktop manager — an optional Tauri app: live console, start/stop, and one-click MCP setup for 9 AI agents.

Requirements

• Node.js 18+
• A Godot 4.x editor binary — the server can download one automatically, or you can point it at an existing install with GODOT_BIN.
• Network access for the first toolchain/doc download (not needed afterwards, or at all if you set GODOT_BIN and skip docs search).

Install

git clone https://github.com/Fulviuus/godot-mcp.git && cd godot-mcp
npm install
npm run build      # generates dist/index.js
npm test           # runs the test suite (optional)

Configuration

Add the server to your MCP client. For a stdio config (Claude Code / Claude Desktop style):

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/index.js"],
      "env": { "GODOT_PROJECT_ROOT": "/path/to/your/game" }
    }
  }
}

Or run it over HTTP (shared by multiple agents):

node dist/index.js --transport http --port 7878
# then point clients at http://127.0.0.1:7878/mcp

Don't want to edit config files by hand? The desktop app writes the right config into each agent for you.

CLI options

Flag	Default	Purpose
--transport <stdio|http>	stdio	Transport to serve on.
--host <host>	127.0.0.1	HTTP bind host.
--port <port>	7878	HTTP bind port.
--exit-with-parent	off	Exit when the controlling stdin/parent closes.
--version, --help	—	Print version / usage.

Environment variables

Variable	Purpose
GODOT_PROJECT_ROOT	Default project root (folder with project.godot).
GODOT_BIN	Path to a pre-installed Godot editor binary; skips downloads.
GODOT_MCP_CACHE_DIR	Where to cache editors/templates/docs (default ~/.cache/godot-mcp).
GODOT_MCP_MONO	Set to 1 to use the .NET/Mono build.
GODOT_MCP_LOG_LEVEL	debug / info / warn / error.

Most tools also accept a project_root and version argument to override the defaults per call.

Tools

28 tools across eight areas. Every tool accepts response_format: "markdown" | "json".

Area	Tools
Project	godot_project_info, godot_get_settings, godot_set_setting, godot_list_addons
Resources	godot_list_resources, godot_parse_resource, godot_create_resource, godot_find_references
Build	godot_setup, godot_build, godot_export, godot_clean, godot_doctor
Runtime	godot_run, godot_stop, godot_game_logs, godot_list_games
Live engine	godot_engine_info, godot_scene_tree, godot_eval, godot_set_node_property, godot_hot_reload, godot_engine_command
Editor	godot_validate_script, godot_install_bridge
Screenshot	godot_screenshot
Docs	godot_api_search, godot_api_doc

A typical agent flow:

godot_project_info            → understand the project
godot_setup                   → provision editor + templates + bridge
godot_build                   → confirm it imports/compiles
godot_run live:true           → launch with live control
godot_scene_tree / godot_eval → inspect the running game
godot_hot_reload              → apply script changes without restarting
godot_screenshot              → see the result
godot_export preset:"Linux"   → produce a build

The live-control bridge

Godot's headless mode can't render and has no general runtime RPC, so live control is provided by a tiny bridge addon (addons/godot_mcp) that godot_setup (or godot_run live:true) installs into your project. It registers an autoload that, only when a port is provided, opens a localhost TCP socket speaking newline-delimited JSON. The server uses it for godot_eval, godot_scene_tree, godot_set_node_property, godot_hot_reload and godot_screenshot. It is inert during normal runs and easy to remove (delete the addons/godot_mcp folder and the MCPBridge autoload).

Desktop app

desktop/ is an optional Tauri control panel (the Godot counterpart to the defold-mcp manager). It supervises the server and connects it to your agents without touching config files by hand:

• Console — a live stream of everything the server does (tool calls, export output, game logs, listener status).
• Server control — start/stop the server in Streamable HTTP mode on a chosen host/port (default 127.0.0.1:9820), with a status pill showing the live tool count and PID.
• Agent auto-configuration — pick an agent and click Configure: the app merges a godot entry into that agent's own MCP config file (backing it up first) in the client's correct dialect, over HTTP or stdio. Supported agents: Claude Code, Claude Desktop, OpenAI Codex, Cursor, Gemini CLI, VS Code (Copilot), Windsurf, Cline, Zed. Files it can't safely edit (e.g. JSONC with comments) are never modified — it shows a paste-ready snippet instead.

The server is bundled into the app, so end users only need Node installed. See desktop/README.md to build and run it.

Architecture

src/
├── index.ts            Entry point: server construction, stdio/HTTP, lifecycle
├── http.ts             Streamable HTTP transport + /health
├── constants.ts        Versions, release-asset naming, cache locations
├── context.ts          Project-root resolution, res:// ↔ filesystem mapping
├── state.ts            Running-game registry + log buffers
├── util/               Parsers & helpers (ini, scene, gdscript, csharp, fs, http)
├── services/           Engine-facing logic (toolchain, processes, engine bridge,
│                       refdoc, screenshot, editor, templates)
└── tools/              MCP tool modules (project, resources, build, run, engine,
                        editor, screenshot, docs) + shared registration

desktop/                Optional Tauri desktop manager (see desktop/README.md)
test/                   node --test suite + a minimal Godot fixture project

The engine-specific layers map cleanly onto Godot: the godot editor binary + export templates replace Defold's bob.jar; the text scene format replaces protobuf; GDScript/C# replace Lua; and the bridge replaces Defold's TCP engine service.

Development

npm run dev          # run from source with tsx
npm run build        # type-check + emit dist/
npm test             # unit + server (stdio) + http tests
npm run bundle:server  # esbuild single-file bundle (used by the desktop app)

The toolchain-dependent flow (setup → build → run → eval → screenshot → export) is covered by an opt-in smoke test that needs a real Godot install:

node test/live-smoke.mjs            # uses a temp copy of the fixture
node test/live-smoke.mjs /my/game   # or your own project

Desktop app (Rust/Tauri) tests:

cd desktop/src-tauri && cargo test   # config writers, merging, backups

License

MIT — see LICENSE.