# Beckett — MCP for Godot

> *Stop waiting for Godot.*

[![CI](https://github.com/beckettlab/beckett-godot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/beckettlab/beckett-godot-mcp/actions/workflows/ci.yml)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/pBAugYuerR)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Godot 4.2+](https://img.shields.io/badge/Godot-4.2%2B-478CBF?logo=godotengine&logoColor=white)](https://godotengine.org)
[![MCP](https://img.shields.io/badge/MCP-server-5A45FF)](https://modelcontextprotocol.io)
[![Release](https://img.shields.io/github/v/release/beckettlab/beckett-godot-mcp?logo=github)](https://github.com/beckettlab/beckett-godot-mcp/releases)
[![Stars](https://img.shields.io/github/stars/beckettlab/beckett-godot-mcp?logo=github)](https://github.com/beckettlab/beckett-godot-mcp/stargazers)
[![Last commit](https://img.shields.io/github/last-commit/beckettlab/beckett-godot-mcp)](https://github.com/beckettlab/beckett-godot-mcp/commits)

**Beckett** is a **zero-sidecar** Model Context Protocol (MCP) server embedded directly in the **Godot 4** editor as a GDScript `EditorPlugin`. AI agents (Claude and others) drive the editor over HTTP — no Node/Python bridge, no second process, no cloud.

This repository is the free, **MIT-licensed Lite edition**: the complete **inspect → author → run → SEE** dev loop (55 tools), for **GDScript *and* C#**. The AI can now *watch your running game* on the free tier: screenshot it, read the live remote scene tree and node state, poll performance monitors, and tail the game's logs. The paid **Full** edition makes the AI the *playtester* (it drives input, clicks 2D/3D and UI, and asserts the results), plus a test runner, animation tools, `scatter_nodes`, background exports, project-wide analysis, and 46 knowledge packs. See [What Full adds](#what-full-adds).

**Lite: the AI sees your game. Full: the AI playtests it.**

## Demo

[![Watch Beckett drive Godot](https://img.youtube.com/vi/oUHrA4ojqdg/maxresdefault.jpg)](https://www.youtube.com/watch?v=oUHrA4ojqdg)

## Why

Existing Godot MCP servers either shell out to the CLI (can't play the game, screenshot, or inspect runtime) or run a Node/Python **sidecar** that relays to a thin in-editor addon. This one makes the **addon itself the MCP server**, and exposes **reflection-generic** tools that work on *any* class via `ClassDB` — instead of hundreds of hand-coded per-domain wrappers (an anti-pattern: LLMs degrade past ~40 tools).

## Highlights

- **Zero-sidecar** — `TCPServer` HTTP/JSON-RPC server polled on the editor main thread. No marshalling, nothing extra to install beyond the addon.
- **The AI sees your game (free)** — `screenshot` the running game, read the live remote scene tree (`get_remote_tree` / `find_nodes` / `wait_for_node`), read live node state (`runtime_get_property` / `monitor_properties`), poll `get_performance_monitors`, and tail `game_logs` with stack traces. The free tier can watch and diagnose the running game; **Full closes the loop by driving input and asserting the result.**
- **GDScript and C#, one addon, zero sidecar** — the C#/.NET dev loop is free too: `build_csharp` runs a `dotnet build` compile-check that returns structured `file:line:col` + CS-code diagnostics (safe while the editor is open, no new dependency beyond the .NET SDK a C# project already needs), `write_script` is `.cs`-aware, and reflection surfaces your C# `[GlobalClass]` types just like GDScript `class_name`.
- **Reflection-first + discovery** — `find_classes` / `describe_class` / `find_methods` make the whole engine surface searchable; `describe_object` / `set_property` / `call_method` then drive any `Node` / `Resource` / `Object`. Reaches TileMap, GPUParticles, AnimationTree, NavMesh, shaders… with no per-domain code.
- **GDScript dev-loop with validate-before-write** — `write_script` / `script_patch` parse the code first and refuse to write what doesn't compile (closing the #1 AI-on-Godot failure: hallucinated GDScript). Godot's edge over UE: reload needs no compile step.
- **Undoable authoring** — every scene/node mutation goes through `EditorUndoRedoManager` (atomic + undoable); `batch_execute` rolls a whole batch back on failure.
- **One-step install** — enabling the plugin auto-starts the server and writes `.mcp.json`, so `claude`/Cursor connects with zero hand-editing (no Node.js to install — the competitor needs it just to try).
- **Security** — localhost-only with `Origin` validation (anti DNS-rebind) + optional bearer token; read-only / allowlist / confirm-destructive gates; auto-start is opt-out (`beckett/autostart=false`).
- **Run → see loop** — `play_scene` → `wait_until` → `logs_read` → `screenshot` / `get_remote_tree` → fix: launch the game, tail its output and errors, then look at the running frame and live scene tree to diagnose. (Full closes the loop autonomously: the AI drives the game and asserts.) Plus **MCP Resources + Prompts**.
- **Dock panel** — status, one-click Start/Stop, copy-client-config, and an **AI-effort slider** (1–4 in Lite; L4 = *See*) that caps how many tools are advertised: cheaper model context when you only need a slice. **Applies live, no reconnect** — the server pushes `notifications/tools/list_changed` over its SSE stream and list-changed-aware clients (Claude Code, Cursor, …) re-fetch on the spot.
- **Responsive even unfocused** — while MCP traffic is active the server clamps the editor's low-processor sleep, so calls stay fast when you're focused on the terminal instead of the editor (the usual agent setup).
- **Spec-current MCP** — protocol version negotiation, tool **annotations** (`readOnlyHint`/`destructiveHint`/`openWorldHint`) on every tool, and `structuredContent` (2025-06-18) alongside text results. An **audit ring** (`audit://recent`) records the last 200 tool calls — see everything the AI did.

## Tools (50) · Resources (6) · Prompts (6)

> **Fewer tools, on purpose — that's the moat, not a limitation.** Most Godot MCPs hand-code one tool per task (`create_sprite`, `add_collision`, `make_timer`…) — hundreds that *still* miss classes and flood the model's context (LLMs measurably degrade past ~40 tools). Beckett's are **reflection-generic**: `describe_class` / `set_property` / `call_method` drive *any* of Godot's 1000+ classes through `ClassDB` — TileMap, GPUParticles, AnimationTree, shaders, your own `class_name` or C# `[GlobalClass]` — with no per-domain code. **Don't count tools, count coverage:** a smaller, sharper toolset that reaches the *whole* engine beats a hundred narrow wrappers that don't.

The free Lite edition — the complete inspect → author → run → **see** loop, for GDScript and C#:

- **Reflection / discovery:** `get_godot_version`, `find_classes`, `describe_class`, `find_methods`, `describe_object`, `set_property`, `call_method`, `get_scene_tree`
- **Scene authoring (undoable):** `create_node`, `delete_node`, `rename_node`, `reparent_node`, `duplicate_node`, `move_node`, `instance_scene`, `save_scene`, `open_scene`
- **GDScript dev-loop:** `validate_script`, `write_script`, `script_patch`, `read_script`, `attach_script`
- **C#/.NET dev-loop:** `build_csharp` (a `dotnet build` compile-check returning structured `file:line:col` + CS-code diagnostics, safe while the editor is open, zero new dependency; `write_script` is `.cs`-aware and C# `[GlobalClass]` types show up in reflection)
- **Signals:** `connect_signal`, `disconnect_signal`, `list_signals`
- **Resource assets:** `create_resource`, `set_resource`
- **Files / project:** `read_file`, `write_file`, `list_dir`, `search_files`, `get_project_setting`, `set_project_setting`
- **Run loop:** `play_scene`, `stop_scene`, `get_play_state`, `wait_until`, `logs_read`
- **Runtime observation (the AI sees your game):** `screenshot`, `get_remote_tree`, `find_nodes`, `wait_for_node`, `runtime_get_property`, `monitor_properties`, `get_performance_monitors`, `game_logs`
- **Project / authoring helpers:** `get_project_statistics`, `apply_template`, `batch_execute`
- **MCP Resources:** `scene://tree`, `scene://selection`, `project://settings`, `assets://list`, `log://output`, `audit://recent`
- **MCP Prompts:** `inspect_node`, `audit_scene`, `setup_2d_player`, `fix_script_errors`, `build_test_fix`, `make_game`

## What Full adds

The **Full** edition is the same core plus a premium layer that makes the AI the *playtester*: it sees the screen, presses the buttons, and verifies the result. **91 tools, 46 skill packs** total:

- **The AI drives:** `simulate_input`, UI clicks in 2D + 3D (`click_button_by_text` / `click_control` / `click_node3d` / `click_world`), `scroll` / `drag`, `get_control_rect` / `find_ui_elements`, live `runtime_call` / `runtime_set_property`, and `record_input` / `replay_input`.
- **The AI verifies:** `assert_node_state`, `assert_screen_text`, `assert_scene`, `compare_screenshots`, plus the in-editor **test runner** (`test_run`).
- **Author + ship:** `animation_manage` (keys / tracks / presets), `scatter_nodes` (Scene-Paint mass placement), background `export_project` + `job_status`, project-wide analysis (`find_unused_resources`, `detect_circular_dependencies`), and the Godot **Asset Store / Library** browser-installer (`asset_lib_search` / `asset_lib_info` / `asset_lib_install`).
- **37 skill knowledge packs** (`list_skills` / `load_skill`): gdscript, particles, animation, ui, physics, multiplayer, mobile, and more, so reflection reaches each domain with no per-domain tools.

Full is a one-time purchase ($15) with lifetime updates: **https://beckettlabs.itch.io/beckett-godot-mcp**

## How it compares

Beckett is one of only a few *embedded* (zero-sidecar) servers in the field, and the only one that puts *seeing the running game* in a free tier. The other players have real strengths (raw tool count, mindshare, breadth), so here's an honest side-by-side. (Competitor figures are their own published numbers; they ship far more hand-coded per-domain tools, which is a different design choice, not strictly "more capability": see [Why](#why).)

| | **Beckett Lite** (free, MIT) | **Beckett Full** ($15) | **CLI shell-out** (e.g. Coding-Solo, free) | **Sidecar** (godot-mcp-pro, $15, Node 18+) | **Native** (free, embedded, 4.6+ only) |
|---|:---:|:---:|:---:|:---:|:---:|
| Zero sidecar (no Node/Python) | ✅ | ✅ | ❌ (Node CLI shell-out) | ❌ (Node 18+ + TS server) | ✅ (embedded) |
| The AI **sees** the running game (screenshot, live tree, live state) | ✅ **free** | ✅ | ⚠️ CLI debug output only | ✅ (paid) | ✅ (free) |
| The AI **drives + asserts** (playtest: input, clicks, asserts) | ❌ | ✅ | ❌ | ✅ (input record/replay) | ⚠️ partial |
| Validate-before-write (refuses non-compiling GDScript) | ✅ | ✅ | ❌ | ❌ | ❌ |
| C# + GDScript | ✅ | ✅ | ❌ (GDScript) | ❌ (GDScript) | ❌ (GDScript) |
| Godot 4.2+ | ✅ | ✅ | varies | varies | ❌ (4.6+ only) |
| Tool count | 50 | 80 | ~12 | ~163 | 154 |

*No trash talk intended: Coding-Solo is the mindshare leader (~4,000★), godot-mcp-pro ships the broadest curated toolset (~163) with input record/replay, and Native gives away 154 tools embedded. Beckett's bet is a smaller **reflection-generic** surface that reaches the whole engine, validate-before-write, both languages, 4.2+ reach, and *the AI seeing your game in the free tier*.*

## Use

1. **Install from the editor.** In Godot, open the **AssetLib** tab, search **"Beckett"**, and install ([asset #5296](https://godotengine.org/asset-library/asset/5296)). Or copy `addons/beckett/` into your project manually.
2. Enable **Beckett — MCP for Godot** in *Project → Project Settings → Plugins* (works on Godot **4.2+**; verified on 4.4.1, 4.6.2 & 4.7, CI-tested on Windows, Linux & macOS). Enabling it **auto-starts** the server and **writes `.mcp.json`**. (Opt out: `beckett/autostart=false`, `beckett/auto_write_client_config=false`. Other options: `BECKETT_PORT` default `8770`, `BECKETT_TOKEN`, `BECKETT_READONLY=1`, `BECKETT_ALLOWLIST`, `BECKETT_CONFIRM_DESTRUCTIVE=1`. Panel has Start/Stop.)
3. Connect your client. For **Claude Code**, just run `claude` in the project — the auto-written [`.mcp.json`](.mcp.json) wires it up (`/mcp` → **beckett**). For Cursor/others, point at `http://127.0.0.1:8770/mcp` (Streamable HTTP) or use the panel's **Set up …** buttons. See [INSTALL.md](INSTALL.md).

## Status

This is the free, MIT-licensed **Lite** edition — the **inspect → author → run → see** core: reflection/discovery, scene & script authoring for **GDScript and C#** (with `build_csharp` compile-check), **signals**, **resource create/assign**, **files & project settings**, the **play → wait → `logs_read`** dev loop, and the **runtime-observation** tools that let the AI *see* the running game (`screenshot`, `get_remote_tree`, live node state, perf monitors, `game_logs`), plus **Resources + Prompts + dock panel**. **55 tools.** Built and verified live on Godot 4.4.1, 4.6.2 and 4.7 (headless editor + a real HTTP MCP client), and CI-tested on every push across Windows, Linux, and macOS.

The **Full** edition adds the agent-driven play-test layer (the AI drives input, clicks 2D/3D and UI, and asserts results): the test runner (`test_run`), animation tools (`animation_manage`), `scatter_nodes`, background export jobs, project-wide analysis, and the 40 bundled skill packs. It *playtests* the running game.

## License

**Lite edition — MIT** (this repository). Free and open-source: use it, fork it, ship it. See [LICENSE](LICENSE).

The **Full** edition (the agent-driven play-test layer, background export jobs, and the skill packs) is a separate commercial product — one-time purchase with lifetime updates.

---

*Beckett is a third-party tool, not affiliated with or endorsed by the Godot Foundation. "Godot" is a trademark of the Godot Foundation.*