MCP for Godot

Português do Brasil · Architecture · Security · Tool catalog

MCP for Godot is a local bridge that lets MCP-compatible AI clients inspect, run, observe, and carefully modify one Godot project. It combines a Python stdio MCP server with an opt-in Godot editor addon.

The design starts read-only. Additional capabilities are exposed only through explicit command-line flags. Mutating tools use typed inputs, project-scoped paths, expected hashes or scene revisions, bounded payloads, audit records, and rollback where the operation can provide it.

Preview: version 0.10.0 exposes 65 tools in the complete profile and 20 tools in the default read-only profile. Some protected editor operations need optional native hooks that are not included in this public repository. The server reports those capabilities instead of silently claiming support.

What it can do

• Inspect project files, editor state, open scenes, scene trees, nodes, graphics resources, dependencies, import metadata, and recent process output.

• Observe an opted-in running 2D scene through bounded live snapshots, a frame timeline, performance counters, viewport metadata, and on-demand PNG capture.

• Start and stop a managed editor or game process and run headless validation.

• Preview and apply guarded scene, resource, texture-import, and GDScript changes when the corresponding permissions are enabled.

• Record summarized operations without storing bridge tokens or script bodies.

• Serve both legacy MCP 2025-11-25 initialization and request-scoped 2026-07-28 discovery.

Related MCP server: godot-devtool

Trust model in one minute

1. One MCP process controls one explicit project directory.

2. The addon listens on 127.0.0.1 and creates a random session token under .godot/ai_mcp/bridge.json.

3. Read-only tools are the default. Flags add narrowly defined capabilities.

4. Paths are restricted to res://; traversal, links, hidden targets, oversized messages, and unsupported file types are rejected.

5. This is a local trusted-workstation boundary. Another process running as the same user and able to read the project may also read the bridge token.

Read the full security model before enabling writes, script changes, input injection, or image capture.

Requirements

• Python 3.11 or newer

• Godot 4.7.2 for the tested compatibility target

• An MCP client that can launch a local stdio server

Quick start

Clone and install the Python server:

git clone https://github.com/Dev-Encrypted/mcp-for-godot.git
cd mcp-for-godot
python -m venv .venv
python -m pip install -e .

Install the addon into a Godot project:

.\scripts\install-addon.ps1 -Project "C:\path\to\my-game"

Or on macOS/Linux:

./scripts/install-addon.sh /path/to/my-game

In Godot, enable MCP for Godot in Project > Project Settings > Plugins and keep that editor open. Then configure your client from the templates in clients/.

Run the server directly to verify its CLI:

mcp-for-godot --project /path/to/my-game --godot /path/to/godot

The command communicates over stdio, so normal diagnostics go to stderr.

Permission profiles

Counts are contractual tests for v0.10.0. A tool can still report a structured unavailable result when the editor, live game, renderer, or native hook it depends on is absent.

Live observation is opt-in

Installing the addon does not instrument every game scene. To expose runtime data, attach res://addons/mcp_for_godot/runtime_probe.gd to one node in the scene, preferably named AIMonitor, and run the scene through an editor with the debugger connected. The sample project shows the expected setup.

The collector limits tree size, viewport count, payload size, text fields, and sample frequency. Pixel capture requires --allow-capture and is performed on demand. See live telemetry.

Stock Godot and optional native hooks

The public package works with stock Godot for project inspection, the local bridge, live opt-in observation, process lifecycle, and supported public editor APIs. Native shader parsing, protected scene history, and native debugger event buffers report unavailable when the editor lacks the corresponding optional C++ hooks. See the exact matrix in compatibility.

Tests

python -m unittest discover -s tests -v

To include the real-editor addon parse smoke test:

$env:GODOT_BIN = "C:\path\to\Godot_v4.7.2-stable_win64_console.exe"
python -m unittest discover -s tests -v

The suite covers protocol negotiation, capability filtering, path confinement, transaction preview/apply/rollback behavior, addon packaging, and optional headless editor loading. GPU rendering, driver behavior, and visual correctness still require hardware-specific validation; a headless pass is not treated as proof of those properties.

Project status

This repository contains the MCP server and editor addon. Optional native hooks are outside this distribution. Planned work is tracked in ROADMAP.md, with objective gates for broader backend and AI-client compatibility.

License

Original code in this repository is released under the Apache License 2.0. Godot attribution and trademark information are in THIRD_PARTY_NOTICES.md.