godot-ai 0.4.1

Production-grade MCP server and AI tools for the Godot engine

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.

Status: early, usable, and still expanding.

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

Pick a client in the dock's Clients dropdown and press Configure. The plugin writes the right config for:

• Claude Code (CLI)
• Claude Desktop (via npx mcp-remote bridge)
• Codex
• Antigravity

If auto-configure can't find the client's CLI (GUI-launched editors have limited PATH), the dock shows a Run this manually panel with a copyable command — or use the commands below directly.

Manual configuration

Server URL: http://127.0.0.1:8000/mcp

Claude Code (CLI):

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

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add under mcpServers:

"godot-ai": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
}

Requires Node.js (npx). Restart Claude Desktop after editing.

Codex — edit ~/.codex/config.toml and add:

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

Antigravity — edit ~/.gemini/antigravity/mcp_config.json and add under mcpServers:

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

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.

---

Available Tools

Sessions and Editor

Tool	Description
session_list	List connected Godot editor sessions
session_activate	Set the active session for multi-editor routing
editor_state	Read Godot version, project name, current scene, and play state
editor_selection_get	Read the current editor selection
logs_read	Read recent MCP log lines from the editor
editor_reload_plugin	Reload the Godot editor plugin and wait for reconnect

Scene and Nodes

Tool	Description
scene_get_hierarchy	Read the scene tree with pagination
scene_get_roots	List open scenes in the editor
node_create	Create a node by type with optional name and parent path
node_find	Search nodes by name, type, or group
node_get_properties	Read all properties for a node
node_get_children	Read direct children for a node
node_get_groups	Read group membership for a node

Project and Testing

Tool	Description
project_settings_get	Read a Godot project setting by key
filesystem_search	Search project files by name, type, or path
test_run	Run GDScript test suites inside the editor
test_results_get	Read the most recent test results without rerunning

Client Setup

Tool	Description
client_configure	Configure a supported MCP client from the editor
client_status	Check which supported clients are configured

MCP Resources

Resource URI	Description
godot://sessions	Connected editor sessions with metadata
godot://scene/current	Current scene path, project name, and play state
godot://scene/hierarchy	Full scene hierarchy from the active editor
godot://selection/current	Current editor selection
godot://project/info	Active project metadata
godot://project/settings	Common project settings subset
godot://logs/recent	Recent editor log lines

Manual Client Configuration

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
    }
  }
}

How It Works

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.

Contributing

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

---

License: MIT | Issues: GitHub