godot-ai

# Godot AI Godot AI connects MCP clients like Claude Code, Claude Desktop, Codex, and Hermes Agent to a live Godot editor. It provides 46 tools and 120+ operations that let AI assistants build scenes, edit nodes and scripts, wire signals, and configure UI, materials, animation, particles, cameras, and environments. ## Quick Start ### Requirements - Godot 4.7+ (within the 4.x line) for Godot AI v4 - uv (provides uvx for the Python server) - An MCP client ### Installation 1. **New project:** Download a published version from GitHub Releases and install the add-on at `your-project/addons/godot_ai/` with `plugin.cfg` inside that directory. 2. **Existing installation:** Use the Update button in the Godot AI dock. The final signed v3 release supports one-click migration to v4. ### Enable the Plugin In Godot: **Project → Project Settings → Plugins → Godot AI**. The plugin starts the MCP server and shows connection status in the Godot AI dock. ### Connect Your MCP Client In the dock, press **Configure** next to your client, or **Configure all** for every detected client. Supported clients include Claude Code, Claude Desktop, Codex, Antigravity, Hermes Agent, DeepSeek Harness, Cursor, and VS Code. ### Try It Example prompts: - "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 voxel block-world game with a player, blocks to place and destroy, and save slots." ## How It Works ```text MCP client → godot-ai attach (stdio) → Python server (authenticated HTTP, port 8000) → Godot editor plugin (authenticated WebSocket, port 9500) ``` Both local hops use independent rotating capabilities; neither falls back to unauthenticated access. The editor WebSocket stays loopback-only. For agents in containers or on other machines, run the bridge on the editor machine over SSH. ## Telemetry and Privacy Usage telemetry records an installation UUID, event, outcome, duration, platform, and version—not code, scene contents, or project/file names. Project-directory slugs are hashed before transmission. Opt out with `GODOT_AI_DISABLE_TELEMETRY=true` or `DISABLE_TELEMETRY=true`. ## Documentation and Help ### Bazzite / Fedora Atomic Desktop Issue On Bazzite and other Fedora Atomic desktops, `/home` is normally a symbolic link to `/var/home`. Godot AI 4.0.2 and earlier refuse every capability-directory path that passes through a link. The next release follows a link when it is root-owned and sits in a root-owned directory that other accounts cannot write. For 4.0.2 or earlier, set `GODOT_AI_CAPABILITY_DIR` to a canonical path and launch both Godot and your MCP client from that terminal. ### Reference and Support - Tools, operations, and resources - Write and run tests for your game - Client configuration details - Upgrading from v3 and recovering interrupted migrations - Changelog - Contributing and development setup - Discord for questions and showcases; GitHub Issues for bug reports **License:** MIT