Godot MCP
Godot MCP connects Claude, Cursor, Copilot and other AI agents to the Godot editor. Start here for installation, setup, tools, extensions and the CLI.
Godot MCP is the Godot addon of AI Game Developer. It lets an AI agent such as Claude Code, Cursor, GitHub Copilot, Codex or Gemini work inside the Godot editor: query and edit the scene tree, open and save .tscn scenes, change .tres resources and project settings, read and write C# and GDScript files, build the C# project, run C# snippets in the editor and take screenshots the model can look at. This wiki explains how to install it, connect an AI client and use it day to day.
What Godot MCP is
Godot MCP is a C# editor addon (the folder addons/godot_mcp/, shown in Project Settings as Godot-MCP) that runs inside a Godot 4 .NET project. When the editor loads it, the addon opens a dock called AI Game Developer and connects to an MCP server. The AI agent you chat with connects to the same server and calls the addon's tools through the Model Context Protocol (MCP).
The addon is open source (Apache-2.0) and lives in the Godot-MCP repository. It shares its MCP and reflection libraries with Unity MCP and Unreal MCP, so the three engine plugins behave the same way and use the same cloud account.
How the pieces fit together
| Piece | What it does |
|---|---|
| Godot MCP addon | Runs in the Godot editor, exposes the AI tools and connects to an MCP server. |
| MCP server | The cloud server at ai-game.dev (default), or your own server running on your machine. |
| AI client | Claude Code, Cursor, VS Code Copilot, Codex, Gemini or any other MCP client. It connects to the same server. |
godot-cli | The npm command-line tool that installs the addon, signs you in, writes AI client configs and opens the editor. |
| AI Game Dev app | The desktop app that can install the addon and open the editor for you, without a terminal. |
In the default Cloud mode nothing runs on your machine except Godot and your AI client: the editor and the agent both connect to the hosted endpoint, and you sign in once with your ai-game.dev account. In Custom mode the addon can download and start a local MCP server for you, so everything stays on your computer.
Requirements at a glance
- The .NET (mono) build of Godot 4.3 or newer. The standard GDScript-only build cannot compile the addon.
- The .NET 8 SDK.
- A Godot project with a C#
.csproj. Your own game code can still be GDScript; the addon needs the C# project only to compile itself. - An AI client that speaks MCP.
The full list, including the NuGet packages your .csproj needs, is on Installation.
Quick start
If you are comfortable with a terminal, these commands take a Godot C# project from nothing to a connected AI agent:
npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject
godot-cli login
godot-cli setup-mcp claude-code ./MyGodotProject
godot-cli open ./MyGodotProjectThen ask your agent something like "Add a Node3D scene with a Camera3D and a MeshInstance3D cube, then save it as Main.tscn". The Getting started page walks through the same steps with explanations, and the site's quickstart covers all three engines.
Pages in this wiki
- Installation: every install path (desktop app,
godot-cli, Asset Library, release zip) and the exact NuGet packages. - Getting started: first connection, first prompts and how to check that everything works.
- Connecting AI clients: Cloud endpoint vs your own server, the device sign-in, project keys and
setup-mcpfor each agent. - Configuration: the AI Game Developer dock, saved settings and the
GODOT_MCP_*environment variables. - Tools: the built-in tool families, RQL, and what each tool is for.
- Custom tools: write your own MCP tools in C#, and expose tools from a running game.
- Extensions: optional packages for animation, CSG, navigation, tilemaps and popular Godot addons.
- godot-cli reference: every
godot-clicommand and its flags. - Troubleshooting: the addon does not load, the agent sees no tools, reload problems.
- FAQ: short answers to common questions.
More on the site
- Install Godot MCP: the Godot install page.
- Godot tools catalog and Godot extensions.
- Best practices for Godot: how to write prompts that work well.
- MCP endpoint and authentication: the hosted endpoint and how sign-in works.
- The AI Game Dev app wiki, and the wikis for Unity MCP and Unreal MCP.
- InstallationInstall the Godot MCP addon with the AI Game Dev app, godot-cli, the Godot Asset Library or a release zip, with the exact NuGet packages for your .csproj.
- Getting startedConnect Godot MCP to the cloud, wire up an AI agent such as Claude Code, check the connection and run your first AI prompts in the Godot editor.
- Connecting AI clientsConnect Claude Code, Cursor, Copilot, Codex, Gemini and other MCP clients to Godot MCP through the ai-game.dev cloud endpoint or your own local server.
- ConfigurationConfigure Godot MCP in the AI Game Developer dock, choose which tools AI agents see, and override settings with GODOT_MCP_* environment variables.
- ToolsThe Godot MCP tools AI agents use in the Godot editor, RQL queries for nodes, scenes and resources, C# and GDScript scripts, screenshots and in-game tools.
- Custom toolsWrite your own Godot MCP tools in C#, run Godot API calls on the main thread, and expose tools, prompts and resources from a running Godot game.
- ExtensionsInstall optional Godot MCP extensions for AnimationPlayer, CSG, GridMap, navigation, particles, TileMapLayer, Beehave, Dialogic, Phantom Camera and Terrain3D.
- godot-cli referenceEvery godot-cli command and flag for Godot MCP, from install-plugin, login and setup-mcp to open, exec, run-tool, configure and install-extension.
- TroubleshootingFix common Godot MCP problems, from an addon that does not load or compile to an empty Extensions list, missing tools, reload errors and .NET 10 crashes.
- FAQShort answers about Godot MCP, the AI assistant for the Godot editor: Godot versions, GDScript projects, offline use, cost, security and exported games.