Godot AI

Connect MCP clients directly to a live Godot editor. Godot AI bridges AI assistants (Claude Code, Codex, Antigravity, etc.) with your Godot Editor via the Model Context Protocol. Inspect scenes, create nodes, search project data, run tests, and read structured editor resources — all from a prompt.

Independent community project, not affiliated with the Godot Foundation. Godot Engine is MIT-licensed.

Quick Start

Prerequisites

• Godot 4.3+ (4.4+ recommended)
• uv (used to install the Python server)
• An MCP client (Claude Code | Codex | Antigravity)

1. Install the plugin

Clone the repo (or download the zip) and copy the plugin into your Godot project:

git clone https://github.com/hi-godot/godot-ai.git
cp -r godot-ai/plugin/addons/godot_ai your-project/addons/

2. Enable the plugin

In Godot: Project > Project Settings > Plugins — enable Godot AI.

The plugin will automatically start the MCP server, connect over WebSocket, and show status in the Godot AI dock.

3. Connect your MCP client

The dock lists every supported client in a scrollable grid with a status dot
and per-row Configure / Remove buttons. Press Configure all to set
up every client at once. Auto-configure handles:

• Claude Code — CLI (claude mcp add)
• Claude Desktop — JSON config + npx mcp-remote stdio bridge
• Antigravity — JSON config

• Codex — TOML (~/.codex/config.toml)
• Cursor — ~/.cursor/mcp.json
• Windsurf — ~/.codeium/windsurf/mcp_config.json
• VS Code & VS Code Insiders — <user>/Code/User/mcp.json
• Zed — ~/.config/zed/settings.json (via npx mcp-remote)
• Gemini CLI — ~/.gemini/settings.json
• Cline, Kilo Code, Roo Code — VS Code extension globalStorage
• Kiro — ~/.kiro/settings/mcp.json
• Trae — <user>/Trae/User/mcp.json
• Cherry Studio — <user>/CherryStudio/mcp_servers.json
• OpenCode — ~/.config/opencode/opencode.json
• Qwen Code — ~/.qwen/settings.json

If auto-configure can't find a CLI (GUI-launched editors have a limited PATH),
each row exposes a Run this manually panel with a copyable snippet. Server
URL is always http://127.0.0.1:8000/mcp.

Adding a new client: drop a clients/<name>.gd descriptor under
plugin/addons/godot_ai/clients/ and add one preload(...) line to
clients/_registry.gd. No edits to dock or facade required.

4. Try it

• "Show me the current scene hierarchy."
• "Create a Camera3D named MainCamera under /Main."
• "Search the project for PackedScene files in ui/."
• "Run the scene test suite."
• "Build a neon space city with glass towers, glowing planets, and fire / magic / spark particle effects."

An AI-authored scene: 10 emissive buildings, 3 glowing planets, Tron-style floor strips, and 6 varied particle effects — every node, material, and preset placed by MCP tool calls.

Sessions and Editor

Scene and Nodes

Scripts and Signals

Resources, Materials, Textures

UI, Controls, Theme

Animation

Audio

Particles, Environment, Camera

Project, Filesystem, Input

Testing and Client Setup

Claude Code

claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8000/mcp

Codex (~/.codex/config.toml)

[mcp_servers."godot-ai"]
url = "http://127.0.0.1:8000/mcp"
enabled = true

Antigravity (~/.gemini/antigravity/mcp_config.json)

{
  "mcpServers": {
    "godot-ai": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "disabled": false
    }
  }
}

MCP Client
   | HTTP (/mcp)
   v
Python Server (FastMCP)      port 8000
   | WebSocket               port 9500
   v
Godot Editor Plugin
   | EditorInterface + SceneTree APIs
   v
Godot Editor

The plugin starts or reuses the Python server, connects over WebSocket, and exposes editor capabilities as MCP tools and resources over HTTP.

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License: MIT | Issues: GitHub