beckett-godot-mcp

# 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 (55) · 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`, `ui_snapshot` (every visible Control as structured state in one call), `get_remote_tree`, `find_nodes`, `wait_for_node`, `runtime_get_property`, `monitor_properties`, `get_performance_monitors`, `game_logs`
- **Render diagnosis:** `render_probe` (why a 3D node is or is not on screen, as data: visibility chain, frustum, cull mask, material cull mode, triangle winding) and `set_debug_draw` (switch the running game's debug draw mode, then `screenshot` one render stage)
- **Project / authoring helpers:** `get_project_statistics`, `apply_template`, `batch_execute`, `doctor` (one-call self-diagnosis: edition, effort cap, server and auth state, client configs, and what the tool list costs your context per tier), `help` (any tool's full argument catalogue, on demand)
- **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`).
- **46 skill knowledge packs** (`list_skills` / `load_skill`): gdscr