IvanMurzak/Godot-MCP

')
  
  
  
  
  
  
  
  
  
  
  
Godot MCP is an AI-powered game development assistant **for the Godot Editor**. Connect **Claude**, **Cursor**, **Copilot**, or any MCP-aware agent to Godot and let it inspect and drive your project — create nodes, edit scenes, manage resources and scripts, capture screenshots, and more.
Godot-MCP is the Godot counterpart of Unity-MCP: a C# **editor addon** that exposes Godot Editor operations as **AI Tools** and connects them to an MCP server through the same hosted cloud backend (ai-game.dev) that powers Unity-MCP — or your own self-hosted server. The MCP / reflection stack is **not forked**: it is shared with Unity-MCP and consumed from nuget.org as PackageReferences.
> **💬 Join our Discord Server** — Ask questions, showcase your work, and connect with other developers!
- ✔️ **AI agents** — Use the best agents from **Anthropic**, **OpenAI**, **Google**, or any other provider with no vendor lock-in
- ✔️ **42 built-in Tools** — A wide range of MCP Tools across 12 families for operating the Godot Editor
- ✔️ **C# & GDScript** — Read, create, and update both .cs and .gd scripts, and attach them to nodes
- ✔️ **Scene & Node control** — Build and edit the scene tree, open/save .tscn scenes, mutate .tres/.res resources
- ✔️ **Visual feedback** — Capture viewport, camera, and isolated-node screenshots the LLM can inspect
- ✔️ **Reflection escape hatch** — Find and call any C# method across loaded assemblies via ReflectorNet
- ✔️ **Cloud or self-hosted** — Connect to ai-game.dev out of the box, or point at your own server
- ✔️ **Natural conversation** — Chat with AI like you would with a human
Quick Start
Get up and running from a terminal using the godot-cli (the Godot analog of unity-mcp-cli) — no manual file copying or csproj editing required:
That's it. Ask your AI *"Create 3 cubes in a circle with radius 2"* and watch it happen. ✨
> **Offline / dev install:** install-plugin --source /addons/godot_mcp copies the addon from
> a local directory instead of downloading it. Prefer the matching release version with
> install-plugin --version if you need a specific addon build. The manual route (copy the
> addon + add the NuGet packages yourself) is still documented under Installation
> Steps 1–2 for the Asset Library / hand-managed flows.
> See the full CLI documentation for every command, editor-resolution order, and connection env vars.
Contents
- Quick Start
- Tools Reference
- Requirements
- Installation
- Step 1: Add the addon
- Option A — Godot Asset Library (recommended)
- Option B — GitHub Release zip
- Option C — copy from source
- Step 2: Add the NuGet packages
- Step 3: Install an AI agent
- Connect
- Cloud mode (default) — ai-game.dev
- Custom mode — your own server
- Godot MCP Server setup
- Local server — let the addon download & run it for you
- Build & run the server manually (advanced)
- Customize Tools
- Runtime usage (in-game)
- Capturing in-game runtime errors
- Sample: a live game-state tool
- Where the server URL and token come from
- Security: opt-in only, default OFF
- How Godot MCP Architecture Works
- Building & contributing
- License
Tools Reference
Godot-MCP ships **42 built-in tools** grouped into **12 families**. Tool names mirror Unity-MCP where
sensible (scene-*, node-*, …). Every tool returns a structured, ReflectorNet-serialized
result (or a PNG image for screenshots). All editor tools are available immediately after the addon is
enabled — no extra configuration required. The **runtime-errors** family is the exception: it surfaces
errors from the *running game* and is **OFF by default** — opt in with builder.WithRuntimeErrorCapture()
(see Capturing in-game runtime errors).
| Family | Tools | What it does |
| --- | --- | --- |
| **ping** | ping | Lightweight readiness probe — echoes a message back, or returns pong. Verifies the end-to-end MCP path (editor → SignalR → tool dispatch). **System tool** — reachable over the server's /api/system-tools/ HTTP surface, not advertised to AI agents in tools/list. |
| **node** | node-find, node-create, node-modify, node-set-parent, node-reorder, node-duplicate, node-delete | Inspect and edit the active scene tree (the Godot analog of Unity GameObjects), driving EditorInterface on the main thread. Child order — which is layout order in a VBoxContainer/HBoxContainer — is settable both on creation (node-create's index) and afterwards (node-reorder). |