godot-omni
README.md
<div align="center">
# Godot MCP
### Free and Open-Source Model Context Protocol Automation Plugin for the Godot Engine
[](https://modelcontextprotocol.io)
[](https://github.com/bebabinlarsson-blip/Godot-MCP/releases)
[](https://godotengine.org)
[](https://www.python.org)
[](LICENSE)
[](LICENSE)
[](https://github.com/bebabinlarsson-blip/Godot-MCP)
<br>
<img src="docs/hero.png" alt="Godot MCP Banner" width="100%">
<br>
**100% Free & Open Source | Local by Default | No npm Packages | Optional Public Tunnel**
<br>
**Compatible AI Clients**
[Claude Code](https://claude.ai) | [Cursor](https://www.cursor.com) | [Antigravity](https://antigravity.google) | [VS Code / Cline](https://code.visualstudio.com) | [Windsurf](https://codeium.com/windsurf) | [GitHub Copilot](https://github.com/features/copilot) | [OpenAI Codex](https://openai.com)
</div>
---
## Overview
Godot MCP is a free, open-source editor add-on and Python server that connect AI coding assistants to the Godot Editor through the Model Context Protocol (MCP). This README describes [v5.0.39](https://github.com/bebabinlarsson-blip/Godot-MCP/releases/tag/v5.0.39).
Unlike other solutions that rely on external websites, cloud subscriptions, device logins, or custom npm CLI wrappers, Godot MCP is designed to be a straightforward in-engine Godot plugin:
* 100% Free and Open Source: Released under the permissive MIT license. No subscriptions, no paid tiers, and no paywalls.
* Local by default: communication stays on your machine unless you deliberately start a public tunnel. Public tunnels can expose the MCP server outside your network; see the tunnel security notes below.
* Godot add-ons plus Python server: Copy the add-ons into your project, enable them in Godot, and install Python 3.11–3.14 and `uv` so the editor can start the server. No npm or Node.js installation is required.
* Engine Support: Runs as native GDScript in Standard and .NET editions of Godot 4.7 and newer on Windows, macOS, and Linux.
* 81 Tool Families & 1,820+ Operations: Comprehensive scene building, node transformations, procedural animation, tilemap editing, collision creation, and direct GDScript evaluation.
* Single Native Dock: Seamlessly integrated tab directly beside your Inspector with live activity monitoring, connection diagnostics, and memory indicators.
---
## Tool Families and Capabilities Matrix
Godot MCP provides full engine automation across 81 domain families:
| Family | Key Operations | Description |
| :--- | :--- | :--- |
| **ping** | `ping`, `mcp_ping` | Diagnostic readiness probe echoing engine status, version, process frames, and memory metrics. |
| **node** | `node_create`, `node_set_property`, `node_get_properties`, `node_find`, `node_manage` | Find, spawn, modify, reparent, reorder, duplicate, delete, rotate, scale, and translate nodes in 2D and 3D with undo/redo. |
| **scene** | `scene_open`, `scene_save`, `scene_get_hierarchy`, `scene_manage` | Open, save, create, close, inspect root hierarchies, and instantiate PackedScene prefabs. |
| **script** | `script_create`, `script_patch`, `script_attach`, `script_manage` | Create, anchor-patch, read, detach, inspect symbols, validate syntax/compilation, and delete GDScript files. |
| **filesystem** | `filesystem_manage` | List files, read/write text, delete, move, reimport, trigger scans, download assets from URL, and search free CC0 assets. |
| **resource** | `resource_manage` | Search, load, assign, introspect, create, delete, and move .tres/.res assets, curve profiles, and environment setups. |
| **screenshot** | `editor_screenshot`, `camera_manage` | High-fidelity captures of the 3D viewport, 2D viewport, active cameras, running game frames, and isolated node framing. |
| **editor** | `editor_state`, `editor_manage`, `editor_reload_plugin` | Read editor lifecycle, inspect/set node selections, query performance monitors, clear logs, and execute safe restarts. |
| **console** | `logs_read`, `editor_manage(logs_clear)` | Real-time structured log streaming from plugin events, editor output, debugger errors, and game runtime stdout/stderr. |
| **reflection** | `omni_eval`, `omni_manage(call, get, set, inspect)` | Universal object reflection, dynamic method invocation, property getters/setters, and ClassDB discovery. |
| **tilemap** | `tilemap_manage` | Direct editor tile painting, D4 rotation (0, 90, 180, 270 deg), flips, layer queries, and smart multi-genre layout generation. |
| **tileset** | `tileset_manage` | Inspect atlas source tiles, extract texture slices, and introspect physics and navigation layers. |
| **animation** | `animation_create`, `animation_manage` | Create AnimationPlayers, add property/method tracks, insert keyframes, set autoplay, and apply procedural motion presets. |
| **physics** | `collision_shape_create`, `physics_shape_autofit` | Generate 2D and 3D collision bodies, autofit shapes to visual mesh bounds, and configure collision layers. |
| **mesh** | `mesh_create_primitive` | Procedural generation of BoxMesh, SphereMesh, CylinderMesh, PlaneMesh, CapsuleMesh, and PrismMesh objects with materials. |
| **shader** | `shader_create`, `material_manage` | Author GDShader files, create ShaderMaterials, set uniforms, and assign materials to CanvasItem or MeshInstance3D nodes. |
| **game** | `game_manage`, `project_run` | Launch, stop, restart, and command the running game instance with game helper diagnostics. |
| **input** | `input_map_manage` | Configure InputMap actions, bind keyboard and gamepad events, and query registered input actions. |
| **ui** | `ui_manage`, `ui_semantic_tree`, `ui_click`, `ui_type` | Inspect the semantic control hierarchy of the editor UI, click buttons/tabs, and simulate input keystrokes. |
---
## Godot access: settings and visual feedback
The AI can read and change Godot Editor Settings through
`editor_settings_manage` (`list_settings`, `get_setting`, and `set_setting`).
Project Settings are available through `project_manage` (`settings_get` and
`settings_set`). Settings that can execute code during startup are deliberately
restricted; use the validated main-scene and autoload tools for those changes.
`editor_screenshot` returns an actual MCP image block for the editor viewport
or running game when `include_image=true`. Image-capable clients can inspect it
directly. For text-only models, the optional Vision Routing feature can return
a text description instead; see [Vision Routing](docs/vision-routing.md).
Use `batch_execute` when an edit needs several scene operations. It sends the
commands in one MCP call and reduces repeated network round trips; it does not
reduce the physical network latency of a single call.
## Quick Start: 3 Simple Steps
You do not need to register on any website or install any npm packages.
### Step 1: Download and Extract the Plugin
1. Download **godot-mcp-v5.0.39.zip** from the [v5.0.39 release](https://github.com/bebabinlarsson-blip/Godot-MCP/releases/tag/v5.0.39).
2. Extract it into your Godot project root. The ZIP contains both `godot_ai` and `godot_omni` inside `addons/`:
```text
your-godot-project/
└── addons/
├── godot_ai/
│ ├── plugin.cfg
│ ├── plugin.gd
│ ├── godot_mcp_dock.gd
│ ├── connection.gd
│ ├── dispatcher.gd
│ └── handlers/
└── godot_omni/
├── plugin.cfg
├── plugin.gd
├── omni_dock.gd
├── omni_reflection.gd
└── omni_ui_tree.gd
```
### Step 2: Enable the Plugin in Godot
1. Open your project in Godot.
2. Open **Project -> Project Settings -> Plugins**.
3. Enable **Godot MCP Core** and **Godot MCP Omni**.
4. The **Godot MCP** tab will appear beside your Inspector on the right-hand side.
### Step 3: Configure Your AI Client
Install [Python 3.11–3.14](https://www.python.org/downloads/) and [uv (`uvx`)](https://docs.astral.sh/uv/getting-started/installation/) on the computer running Godot. The add-on can configure supported local clients from its dock; for manual setup, use the versioned prebuilt backend wheel below. The first `uvx` launch downloads the pinned Python dependencies. Source builds stay disabled.
#### Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"godot-mcp": {
"command": "uvx",
"args": [
"--isolated",
"--no-config",
"--no-env-file",
"--no-sources",
"--no-build",
"--index-strategy", "first-index",
"--keyring-provider", "disabled",
"--index", "https://pypi.org/simple",
"--default-index", "https://pypi.org/simple",
"--find-links", "https://pypi.org/simple/godot-ai/",
"--link-mode", "copy",
"--from",
"https://github.com/bebabinlarsson-blip/Godot-MCP/releases/download/v5.0.39/godot_ai-5.0.39-py3-none-any.whl",
"godot-ai"
]
}
}
}
```
#### Claude Desktop
Add to `claude_desktop_config.json` (Windows: `%APPDATA%\Claude\claude_desktop_config.json` | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"godot-mcp": {
"command": "uvx",
"args": [
"--isolated",
"--no-config",
"--no-env-file",
"--no-sources",
"--no-build",
"--index-strategy", "first-index",
"--keyring-provider", "disabled",
"--index", "https://pypi.org/simple",
"--default-index", "https://pypi.org/simple",
"--find-links", "https://pypi.org/simple/godot-ai/",
"--link-mode", "copy",
"--from",
"https://github.com/bebabinlarsson-blip/Godot-MCP/releases/download/v5.0.39/godot_ai-5.0.39-py3-none-any.whl",
"godot-ai"
]
}
}
}
```
#### Google Antigravity
In Antigravity or Gemini CLI configuration:
```json
{
"mcpServers": {
"godot-mcp": {
"command": "uvx",
"args": [
"--isolated",
"--no-config",
"--no-env-file",
"--no-sources",
"--no-build",
"--index-strategy", "first-index",
"--keyring-provider", "disabled",
"--index", "https://pypi.org/simple",
"--default-index", "https://pypi.org/simple",
"--find-links", "https://pypi.org/simple/godot-ai/",
"--link-mode", "copy",
"--from",
"https://github.com/bebabinlarsson-blip/Godot-MCP/releases/download/v5.0.39/godot_ai-5.0.39-py3-none-any.whl",
"godot-ai"
]
}
}
}
```
#### VS Code (Cline / Roo Code)
Add to Cline MCP settings:
```json
{
"mcpServers": {
"godot-mcp": {
"command": "uvx",
"args": [
"--isolated",
"--no-config",
"--no-env-file",
"--no-sources",
"--no-build",
"--index-strategy", "first-index",
"--keyring-provider", "disabled",
"--index", "https://pypi.org/simple",
"--default-index", "https://pypi.org/simple",
"--find-links", "https://pypi.org/simple/godot-ai/",
"--link-mode", "copy",
"--from",
"https://github.com/bebabinlarsson-blip/Godot-MCP/releases/download/v5.0.39/godot_ai-5.0.39-py3-none-any.whl",
"godot-ai"
]
}
}
}
```
#### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"godot-mcp": {
"command": "uvx",
"args": [
"--isolated",
"--no-config",
"--no-env-file",
"--no-sources",
"--no-build",
"--index-strategy", "first-index",
"--keyring-provider", "disabled",
"--index", "https://pypi.org/simple",
"--default-index", "https://pypi.org/simple",
"--find-links", "https://pypi.org/simple/godot-ai/",
"--link-mode", "copy",
"--from",
"https://github.com/bebabinlarsson-blip/Godot-MCP/releases/download/v5.0.39/godot_ai-5.0.39-py3-none-any.whl",
"godot-ai"
]
}
}
}
```
Keep Godot open while using the tools. These JSON examples are for clients running on the same computer as the editor. Cloud clients such as ChatGPT Work Mode require a separately configured authenticated HTTPS tunnel; see [Public tunnel access](#public-tunnel-access). A local `uvx` command on a cloud machine cannot reach your Godot editor by itself. The 1,820+ operations are grouped into a smaller MCP tool surface; clients load or search tool schemas according to their own capabilities. An OpenAPI URL alone does not register those tools in a client.
---
## TileMap Authoring and Direct Editor Placement Directive
### The Direct Editor Placement Contract
AI agents connected via Godot MCP follow a strict architectural rule:
* **Always place tiles directly into the open editor scene**: Use `tilemap_manage` (`place_tile`, `set_cell`, `set_cells_rect`, `generate_layout`) to place tiles directly down into the `TileMap` or `TileMapLayer` node.
* **Never write runtime procedural generation scripts in `_ready()`** unless the user explicitly requested runtime procedural level generation.
* **Why this matters**: Direct placement in the editor gives immediate visual feedback, enables manual tweaking in the editor viewport, configures native Godot 2D physics collisions, and saves clean `.tscn` scene files without runtime overhead.
### Dihedral D4 Rotation and Symmetry
Tiles can be rotated clockwise by 90, 180, or 270 degrees and flipped horizontally or vertically with complete mathematical precision using an 8-state transition table that prevents bit-drift:
* 0 degrees: Default orientation (alt = 0)
* 90 degrees: Clockwise rotation (`transpose | flip_h`)
* 180 degrees: Half rotation (`flip_h | flip_v`)
* 270 degrees: Counter-clockwise rotation (`transpose | flip_v`)
### Smart Genre Layout Generation
The `generate_layout` operation can build complete genre-specific level layouts directly in the active editor scene:
* `platformer`: Ground blocks with jump gaps, vertical boundary walls, stepping platforms at reachable jump heights, and floating challenge accents.
* `topdown` / `rpg`: Perimeter stone walls with open doorway transitions, walkable floor tiles, and corner architectural accents.
* `dungeon`: Thick perimeter walls with corridor access, walkable stone paths, and central structural columns.
* `arena`: Symmetrical battle arena boundaries with strategic cover pillars.
---
## Asset Downloader and Free CC0 Search
AI assistants and developers can search for free CC0 assets and download them directly into the Godot project with automatic editor reimport:
### Search Free CC0 Game Assets
Search the built-in catalog of curated CC0 public domain game packs (Kenney tilesets, retro sound effects, UI elements, textures, and 3D models):
```json
{
"op": "search_assets",
"params": {
"query": "platformer",
"category": "tileset",
"limit": 10
}
}
```
### Download Assets into `res://`
Download any asset from a direct URL (or archive package) straight into your project:
```json
{
"op": "download_asset",
"params": {
"url": "https://raw.githubusercontent.com/KenneyNL/Starter-Kits/master/2D%20Platformer/assets/tilemap-characters_packed.png",
"path": "res://assets/tilesets/platformer_packed.png",
"reimport": true
}
}
```
* Single files are written directly and immediately queued for `reimport`.
* ZIP archives (`extract: true`) are safely uncompressed into the destination folder, followed by a full `scan_filesystem` to index all unpacked assets.
---
## The Godot MCP Dock
The single native Godot MCP dock lives beside the Inspector in Godot:
* Live Status: Visual badge displaying connection status ([OK], [IDLE], [WAIT], [ERROR]).
* Tool Call Feed: Live stream of AI commands as they are executed in the engine with millisecond timing.
* Probe Diagnostics: Built-in ping and self-test trigger buttons to verify connection without leaving Godot.
* Memory Metrics: Process frame count, active scene root, and static memory usage metrics.
* Free Port Button: In case port 8000 is held by an orphaned process, a single click clears it and resets the local server.
---
## System Architecture
```mermaid
flowchart TD
subgraph AI_Clients [Local AI Clients]
Claude[Claude Code / Desktop]
Cursor[Cursor IDE]
Antigravity[Google Antigravity]
VSCode[VS Code / Cline / Roo]
Windsurf[Windsurf IDE]
end
subgraph MCP_Server [Local MCP Server]
Stdio[Standard I/O Pipe]
Router[Adaptive Domain Router]
DirectRuntime[Direct Runtime Bridge]
end
subgraph Godot_Editor [Godot Engine Editor]
WSBridge[Local WebSocket :9500]
Dispatcher[McpDispatcher]
OmniHandler[Omni & Reflection Handler]
DomainHandlers[59 Domain Handlers]
EditorDock[Godot MCP Inspector Dock]
end
AI_Clients -->|MCP JSON-RPC| Stdio
Stdio --> Router
Router --> DirectRuntime
DirectRuntime <-->|Local Loopback Only| WSBridge
WSBridge <--> Dispatcher
Dispatcher --> OmniHandler
Dispatcher --> DomainHandlers
Dispatcher --> EditorDock
```
---
## Verification and Diagnostics
From a checkout of this repository with `uv` installed, you can inspect the installation and tool registry:
```bash
# Run the complete test suite
uv run godot-omni self-test
# Inspect tool registry metrics across all 59 domains
uv run godot-omni tools stats
```
---
## Troubleshooting
### Port 8000 In Use
Check which process owns the HTTP port before restarting it. In the Godot MCP dock, use **Free Port & Replace Server** only for a server you own. The editor WebSocket uses port 9500 by default; port 8000 is the local HTTP endpoint.
### Headless Execution
To allow the plugin to run during headless testing or CI:
```powershell
$env:GODOT_AI_ALLOW_HEADLESS="1"
```
### Public tunnel access
The default `localhost.run` tunnel creates a public hostname for the current
connection. That hostname can change after a reconnect. Cloudflare Quick
Tunnels also use temporary hostnames. Neither option reserves a permanent URL.
For a stable hostname, create a named Cloudflare Tunnel in your Cloudflare
account, route the hostname to `http://127.0.0.1:8000`, and keep both the Godot
editor and `cloudflared` running on an always-on machine. Store the tunnel token
in a file (this option requires cloudflared 2025.4.0 or newer) and set:
```sh
GODOT_AI_CLOUDFLARE_TUNNEL_TOKEN_FILE=/path/to/cloudflare-token
GODOT_AI_TUNNEL_PUBLIC_URL=https://mcp.example.com
godot-ai tunnel --provider cloudflare-named
```
On Windows, set the same environment variables in PowerShell before running
`godot-ai tunnel`. The stable hostname is configured in Cloudflare DNS; it
cannot be reserved by this plugin. A hostname stays reachable only while the
machine, editor server, and tunnel process are online.
#### Free stable URL without a custom domain: Tailscale Funnel
Tailscale Funnel can provide a stable `https://<device>.<tailnet>.ts.net` URL
without buying a domain. Install Tailscale and sign in on the always-on
computer that runs Godot. In the Tailscale admin console, enable HTTPS
certificates and Funnel for the tailnet. Then start the MCP tunnel:
```sh
godot-ai tunnel --provider tailscale-funnel --port 8000
```
The command prints the public URL and automatically reconnects if its tunnel
process exits. Use the same `GODOT_AI_AUTH_TOKEN` protection described below.
The URL stays tied to that Tailscale device and tailnet while they remain
configured; it cannot keep the MCP reachable if the computer, Godot editor,
internet connection, or Tailscale service is offline. Funnel is currently a
beta feature and has provider limits, so this is a stable address rather than
an uptime guarantee. Tailscale's Personal plan is free for personal use.
#### Windows one-click Tailscale launcher
The v5.0.39 release includes the installable add-ons archive
(`godot-mcp-v5.0.39.zip`), exact-version backend wheel, and
`Start-Godot-MCP-Tunnel-v5.0.39.bat`.
Install and enable the add-ons first, then set `GODOT_AI_AUTH_TOKEN` in
Windows Environment Variables **before opening Godot**. With Godot open and
the plugin connected, double-click the BAT file. It runs the pinned
`godot-ai tunnel` command and prints the stable public URL. Leave its window
open while using the tunnel.
The Godot editor plugin starts and owns the local MCP server; this launcher
starts the public tunnel to that server. It does not install Godot or Tailscale.
Install Tailscale, sign in, enable Funnel and HTTPS for your tailnet, and make
sure the `tailscale` CLI is available on PATH. Install `uv` so `uvx` is on
PATH as well. The launcher checks for the Bearer token, `uvx`, and Tailscale
before starting.
Treat any public tunnel as an internet-facing endpoint. Configure the same
`GODOT_AI_AUTH_TOKEN` in the MCP server and the AI client's Bearer
authorization. Start Godot with the token set before launching the editor.
Every automated public tunnel provider refuses to start unless `/api/v1/status`
rejects anonymous requests and accepts that token. The `ngrok` provider reads
the endpoint from ngrok's local Agent API at `127.0.0.1:4040`; keep that API
bound to loopback. Share the URL only with intended clients.
The MCP gateway advertises its available tools at `/api/v1/tools` and exposes
the OpenAPI document at `/openapi.json`. The editor and tunnel process must
both remain online for those tools to be reachable.
Open **Remote Setup** in the Godot MCP dock to see the local connection state,
hostname configuration, and setup steps. Run `godot-ai tunnel doctor` to check
the Cloudflare binary, named-tunnel token file, local bearer enforcement, and
the authenticated public status and tool catalog. The doctor never prints
the bearer token or Cloudflare token. Use `--local-only` when your hostname has
not been routed yet.
### Inspect before editing
`project_manage(op="get_map")` provides a small, read-only index of the open
project's scenes, scripts, assets, resources, autoloads, and input actions.
`tileset_manage(op="tileset_diagnose", params={"tileset_path": "res://..."})`
reports atlas and texture problems; pass `check_collision=true` to flag tiles
without polygons on a selected physics layer. Rotated alternatives alone are
not considered broken.
`batch_execute(commands=[...], preview=true)` previews up to 30 `create_node`
or `delete_node` edits in an open scene, shows scene nodes before and after,
and undoes its changes. Call the same batch with `preview=false` to keep it.
Preview does not capture screenshots or support file-writing commands.
Published v5 releases attach an add-ons-only ZIP after the release workflow
verifies its structure and loads it into a fresh Godot project. Extract the ZIP
at the project root, then enable the plugin in Godot's Project Settings.
---
## Author and License
* Project credits: **[Ghosty (@ghostySRC)](https://github.com/ghostySRC)** and **[Bebabin (@bebabinlarsson-blip)](https://github.com/bebabinlarsson-blip)**
* License: [MIT License](LICENSE) (100% Free and Open Source)
For Godot Asset Library listings, use the direct icon files:
[Godot MCP Core](https://raw.githubusercontent.com/bebabinlarsson-blip/Godot-MCP/main/addons/godot_ai/icon.png) ·
[Godot MCP Omni](https://raw.githubusercontent.com/bebabinlarsson-blip/Godot-MCP/main/addons/godot_omni/icon.png).
TDQS
B3.1/5.0
Scored across 100 tools
Disambiguation1/5
Several tools perform the same operation under different names: eval appears in editor_manage, omni_manage, and execute_script; raycasting is duplicated in physics_manage and physics_query_manage; curve creation exists in resource_manage, path_manage, and curve_manage; input simulation is split across game_manage and input_event_manage. An agent will frequently misselect between these duplicate or near-duplicate tools.
Naming Consistency2/5
Most tools follow a snake_case *_manage pattern, but the same capability is named inconsistently (raycast_2d vs intersect_ray_2d, input_key vs simulate_key, editor_manage op=state vs standalone editor_state), and op naming inside *_manage tools mixes styles. The pattern is readable but not predictable enough across 100 tools.
Tool Count1/5
100 tools is far beyond a well-scoped MCP surface. Even a comprehensive Godot development server would struggle to justify this many, and a large portion of them are redundant with each other rather than earning their place.
Completeness4/5
Coverage of the Godot game-development domain is remarkably thorough: scenes, nodes, scripts, resources, UI, input, animation, physics, rendering, networking, localization, and more are present with no obvious dead-end workflows. Minor gaps exist (e.g., no 2D shape cast, some duplicated features are shallow), but the surface is essentially complete.
Maintenance
ActivityMaintained
ResponsivenessUnresponsive