Metadata-Version: 2.4
Name: godot-ai
Version: 4.0.2
Summary: Production-grade MCP server and AI tools for the Godot engine
Author: Godot AI contributors
Project-URL: Homepage, https://github.com/hi-godot/godot-ai
Project-URL: Repository, https://github.com/hi-godot/godot-ai
Project-URL: Issues, https://github.com/hi-godot/godot-ai/issues
Project-URL: Documentation, https://github.com/hi-godot/godot-ai#readme
Keywords: godot,godot-engine,mcp,model-context-protocol,ai,llm,gamedev,editor-plugin
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Code Generators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp==3.4.7
Requires-Dist: anyio==4.14.2
Requires-Dist: mcp==1.29.1
Requires-Dist: websockets==17.1
Requires-Dist: pydantic==2.13.5
Requires-Dist: httpx==0.28.1
Requires-Dist: uvicorn==0.52.4
Requires-Dist: starlette==1.6.0
Requires-Dist: h11==0.16.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: pillow>=10.0; extra == "dev"
Requires-Dist: psutil==7.2.2; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Provides-Extra: build
Requires-Dist: build==1.6.0; extra == "build"
Requires-Dist: pyinstaller==6.22.2; extra == "build"
Dynamic: license-file

<p align="center">
  <img src="docs/hero.png" alt="Godot AI — The wait is over" width="700">
</p>

# Godot AI

[![CI](https://github.com/hi-godot/godot-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/hi-godot/godot-ai/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/hi-godot/godot-ai/graph/badge.svg)](https://codecov.io/gh/hi-godot/godot-ai)
[![Discord](https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/FDZ5fr2QkP)

**Godot AI connects Claude Code, Claude Desktop, Codex, Hermes Agent, and other
[MCP](https://modelcontextprotocol.io/introduction) clients to a live Godot
editor.** Its [46 tools and 120+ operations](docs/TOOLS.md) let AI assistants
build scenes, edit nodes and scripts, wire signals, and configure UI, materials,
animation, particles, cameras, and environments.

<p align="center">
  <img src="docs/images/huddemo.gif" alt="Cyberpunk HUD demo" width="800"><br>
  <em>Built in ~2 hours with Godot AI, without hand-written code or image generation — <a href="https://github.com/hi-godot/cyberpunk-hud-demo">source</a></em>
</p>

## Quick Start

### Requirements

- Godot **4.7+** within the 4.x line for Godot AI v4
- [uv](https://docs.astral.sh/uv/getting-started/installation/), which provides
  `uvx` for the Python server
- An MCP client

### 1. Install or update

**New project:** choose a published version from
[GitHub Releases](https://github.com/hi-godot/godot-ai/releases) and follow its
verification and installation instructions. The add-on belongs at
`your-project/addons/godot_ai/`, with `plugin.cfg` inside that directory.
Use the release's requirements and package—not a source snapshot copied over
an existing installation.

**Existing installation:** click **Update** in the Godot AI dock when an update
is offered. The final signed v3 release supports a one-click migration to v4;
Godot restarts once and owned, supported client entries are migrated
automatically. Do not extract a new add-on over the old tree. See the
[v3 → v4 migration guide](docs/v4-migration.md) for compatibility and recovery.

For development from source, use the [contributor setup](docs/CONTRIBUTING.md).

### 2. 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. If it is missing from the plugin list, check that the file is at
`addons/godot_ai/plugin.cfg`, not `addons/plugin.cfg`.

### 3. Connect your MCP client

In the dock, press **Configure** next to your client, or **Configure all** for
every detected client. If the client does not notice the new configuration,
restart that client.

Supported clients include **Claude Code**, **Claude Desktop**, **Codex**,
**Antigravity**, **Hermes Agent**, **DeepSeek Harness**, **Cursor**, and **VS Code**.
The dock lists all supported clients and provides a **Run this manually**
fallback where needed.

Use the dock-generated command: it includes the matching version, ports,
resolver options, and excluded tool domains. V4 uses `godot-ai attach` over
stdio; a bare `http://127.0.0.1:8000/mcp` entry cannot authenticate or follow
capability rotation. Updates repin owned client entries automatically;
reconfigure after changing ports, telemetry preferences, or tool domains.

**Client exceptions:** Pi Coding Agent needs an MCP extension that reads
`~/.pi/agent/mcp.json`. Cherry Studio is not supported in v4; remove stale v3
entries in Cherry Studio itself.

<details>
<summary><strong>Per-project configuration</strong></summary>

CLI-configured clients default to global `user` scope. Set **Editor Settings →
Plugins → `godot_ai/mcp_client_scope`** to `project` (or `local`, where supported),
then press **Configure** again.

**Configure** removes existing `godot-ai` entries from every scope before
writing the selected one. This can modify a checked-in `.mcp.json`, but does not
touch other server entries. **Remove** affects only the selected scope.

Launch Godot from the project directory so the client CLI writes configuration
in the right place. Claude Code also requires one-time approval from `claude`
run inside that project.

</details>

### 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 voxel block-world game with a player, blocks to place and destroy, and save slots."*

<p align="center">
  <img src="docs/images/blockarena.gif" alt="Block-world game built with Godot AI" width="640"><br>
  <em>A block-world game with a save system, built from a handful of prompts — <a href="https://github.com/dsarno/save-system-godot-claude">source</a></em>
</p>

## 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 remote
access, prefer an SSH-launched attach command on the server host rather than
storing a capability in client configuration.

These controls do not protect against a compromised same-user process. Windows
also does not claim isolation from other local accounts. See the
[security model](docs/plugin-architecture.md#security-model) and
[package trust boundaries](docs/packaging-distribution.md).

## 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`.
Opt-out creates no telemetry UUID, worker, or files.
[Privacy details and editor settings](docs/TELEMETRY.md).

## Documentation and help

### Bazzite / Fedora Atomic Desktop: server exits before publishing capabilities

On Bazzite, `/home` can point to `/var/home` through a symbolic link. Godot AI
v4 rejects capability-directory paths that pass through symbolic links. This
can prevent startup with `Last pending: capability_record`. A Bazzite user
confirmed that selecting the canonical path fixes this ([#993](https://github.com/hi-godot/godot-ai/issues/993)).
Other Atomic Desktop installations with the same home layout may be affected.

Close Godot and your MCP client, then run this in a terminal as your normal user:

```bash
export GODOT_AI_CAPABILITY_DIR="$(
  realpath -m "${XDG_CONFIG_HOME:-$HOME/.config}/godot-ai/capabilities"
)"
install -d -m 700 "$GODOT_AI_CAPABILITY_DIR"
printf 'Using: %s\n' "$GODOT_AI_CAPABILITY_DIR"
```

Launch **both Godot and your MCP client from that terminal** so the backend and
`godot-ai attach` inherit the same directory. A desktop launcher does not
automatically inherit a terminal's `export`; for persistent use, set the same
canonical path in the launch environment of both applications. Retry the
connection and check that the server starts and the client connects. Keep the
directory private to your user; do not copy capability tokens into client
configuration. This workaround is for Linux; `GODOT_AI_CAPABILITY_DIR` is not
supported on Windows.

### Reference and support

- [Tools, operations, and resources](docs/TOOLS.md)
- [Write and run tests for your game](docs/testing.md)
- [Client configuration details](docs/client-configuration.md)
- [Upgrading from v3 and recovering interrupted migrations](docs/v4-migration.md)
- [Contributing and development setup](docs/CONTRIBUTING.md)
- [Discord](https://discord.gg/FDZ5fr2QkP) for questions and showcases;
  [GitHub Issues](https://github.com/hi-godot/godot-ai/issues) for bug reports

## Star History

<!-- Generated by .github/workflows/star-history.yml on the star-history branch. -->
<a href="https://github.com/hi-godot/godot-ai/stargazers">
  <img src="https://raw.githubusercontent.com/hi-godot/godot-ai/star-history/star-history.svg" alt="Star History Chart" width="700">
</a>

**License:** [MIT](LICENSE)
