godotlens-mcp

# GodotLens: Godot's own view of your GDScript project

[![GitHub Release](https://img.shields.io/github/v/release/pzalutski-pixel/godotlens-mcp)](https://github.com/pzalutski-pixel/godotlens-mcp/releases)
[![npm](https://img.shields.io/npm/v/godotlens-mcp)](https://www.npmjs.com/package/godotlens-mcp)
[![PyPI](https://img.shields.io/pypi/v/godotlens-mcp)](https://pypi.org/project/godotlens-mcp/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

An MCP server that lets an AI agent ask **Godot itself** about your project — where a symbol
is used, what a method's real signature is, whether an edit compiles, how a scene is wired —
and run the game, look at it and drive it, so the agent can check that the game does what it
meant without a person playing it.

## Why

An agent editing GDScript from text alone is guessing. It cannot tell a call from a comment,
cannot know which methods exist on a `CharacterBody2D` in *your* Godot version, cannot see that
a signal handler is wired by name inside a `.tscn`, and cannot see what happened at runtime.

GodotLens never answers those questions itself. It asks the engine and returns the engine's
answer. Measured on Godot 4.7.1, in a project where `take_damage` is defined in `player.gd`,
called twice from `enemy.gd`, once from `player.gd`, and named in a comment:

| Approach | Result |
|----------|--------|
| `grep take_damage` | 5 matches, including the comment |
| `gdscript_references` | exactly 4 real call sites; the comment is not among them |

That principle — *delegate every judgement to Godot* — is what makes the answers trustworthy,
and it is why the tool names tell you where an answer came from. `gdscript_*` is the language
server. `scene_*` and `project_*` run the engine on the project. `debug_*` is your editor's
debugger. `runtime_*` is a game GodotLens launched and is connected to.

## Requirements

| | Needed for |
|---|---|
| **Godot 4.6+** editor open on your project | `gdscript_*` and `debug_*` — the language server and debug adapter live inside the editor |
| A Godot **binary** via `GODOT_BIN`, a `./godot/` directory, or `PATH` | `scene_*`, `project_*` and `runtime_*`, which run the engine themselves and need no editor |
| **Python 3.10+**, or **Node.js 16+** for `npx` | running this server |

Godot 4.6 is the floor because the language server changed materially at 4.5 (URI encoding)
and 4.6 (document ownership). Older versions are refused with a clear message rather than
silently misread.

## Install

**npx** (recommended). The package bundles the server; there are no runtime dependencies.

```json
{
  "mcpServers": {
    "godotlens": {
      "command": "npx",
      "args": ["-y", "godotlens-mcp"]
    }
  }
}
```

**pip**

```bash
pip install godotlens-mcp
```

```json
{
  "mcpServers": {
    "godotlens": { "command": "godotlens-mcp" }
  }
}
```

## How to run

| Setup | What works | Do this |
|---|---|---|
| **Your editor is open** — normal development | Everything | Turn on **Import Resources When Unfocused** in Editor Settings (below). |
| **No editor** — CI, scripts | `scene_*`, `project_*`, `runtime_*` | For `gdscript_*` and `debug_*`, start a headless editor: `godot --path <project> --editor --headless --lsp-port 6005 --dap-port 6006` |
| **Games GodotLens launches** (`runtime_run`) | `runtime_*`, beside either of the above | Nothing. Each game is its own process connected to GodotLens; no editor run slot is used. |

**Import Resources When Unfocused.** The editor notices new and changed files only when its
window gains focus. An agent-driven editor never gains focus, so a new `class_name` script stays
unknown — every script using it reports the name as undeclared and the game fails to parse —
and new assets stay unimported. With this setting on, the editor rescans every half second.
It is `interface/editor/behavior/import_resources_when_unfocused` in 4.7 and
`interface/editor/import_resources_when_unfocused` in 4.6; to set it for one project only, put
the 4.6 name under `[editor_overrides]` in `project.godot` (4.7 migrates it on load). When a
synced file names a class the editor has not registered, `gdscript_sync_file` waits briefly,
then says which class and points here.

**Games GodotLens launches.** `runtime_run` starts the game with `--remote-debug` pointing at
GodotLens, so the game connects to GodotLens the way it would to the editor's debugger. Games
are **headless** by default — no window, no sound, nothing takes focus. Pass `windowed: true`
only for `runtime_screenshot`: the window opens at a far-off position with audio muted, and is
then moved fully off-screen, so at most a small corner may show for a moment.
Script errors are reported and never stop the game. A game started this way ends when it is
stopped, when GodotLens exits, and on Windows even if GodotLens is killed outright. Its log,
like that of every engine run GodotLens starts, goes to a temporary file of its own: Godot keeps
only the newest five logs per project, and your own play and test logs stay among them.

**The helper.** `runtime_eval` and `runtime_input` need code inside the game. GodotLens passes
its own `helper.gd` to the game with `--script` for that run only; **nothing is written to your
project**. Godot still loads your project's settings, input map and autoloads, and the helper
opens the scene. A project that sets its own main loop type runs without it, and
`runtime_run` with `helper: false` runs the game exactly as it is.

**Several agents.** Subagents in one Claude Code session share one GodotLens process
(`gdscript_status` and `runtime_status` report its `server_pid`). Calls run concurrently, so a
long `runtime_run` or scene check does not hold up anyone else's query, and each agent can run
its own game with `runtime_run` (`GODOT_RUNTIME_MAX_SESSIONS`, default 4). Two things are not
coordinated: `debug_run` uses your editor's single run slot, so a second run stops the first;
and two agents writing the same file overwrite each other — have one agent write at a time.

## The loop

The tools are designed around one cycle. Read it once and the rest of this document is a
reference.

```mermaid
flowchart LR
    U["<b>Understand</b><br/>gdscript_find<br/>gdscript_references<br/>gdscript_hover"]
    W["<b>Write</b><br/>gdscript_engine_api<br/>gdscript_complete<br/>gdscript_validate"]
    S["<b>Sync</b><br/>gdscript_sync_file"]
    V["<b>Verify</b><br/>gdscript_diagnostics<br/>scene_validate<br/>project_validate"]
    R["<b>Run</b><br/>runtime_run"]
    O["<b>Observe &amp; act</b><br/>runtime_tree · runtime_inspect<br/>runtime_output · runtime_eval<br/>runtime_input · runtime_screenshot"]

    U --> W --> S --> V --> R --> O
    O -- "fix, then runtime_reload" --> W
    O -- "something is wrong" --> U

    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    class U,W,S,V,R,O step;
```

1. **Understand.** `gdscript_find` locates a symbol by name; `gdscript_references` and
   `gdscript_hover` explain how it is used and what type it is.
2. **Write.** `gdscript_engine_api` gives real signatures instead of recalled ones,
   `gdscript_complete` offers scene-aware candidates, and `gdscript_validate` checks proposed
   content *before* it reaches disk.
3. **Sync.** Godot's language server does not watch the filesystem. After editing a `.gd`
   file, call `gdscript_sync_file` or it keeps answering from the old text.
4. **Verify.** `gdscript_diagnostics` for compile errors, `scene_validate` for what the
   compiler cannot see in a scene, `project_validate` after moving files.
5. **Run.** `runtime_run` starts the game and returns its first output and errors.
6. **Observe and act.** See the live tree and values, press inputs, evaluate expressions,
   take a screenshot; fix the code and `runtime_reload` it into the running game.

Two conventions apply throughout:

- **All line and character parameters are 0-indexed**, matching the LSP. Editor line 1 is
  line 0. `gdscript_find` exists partly so you rarely have to compute one by hand.
- **Results carry a `verified` flag** where it matters. `verified: false` with an empty
  diagnostics list means Godot never reported back — that is *not* a clean bill of health.

## Tools

### Understanding code

| Tool | Description |
|------|-------------|
| `gdscript_find` | Locate a declaration **by name**. Returns a position the tools below accept directly. |
| `gdscript_definition` | Where a symbol is defined. |
| `gdscript_references` | Every reference project-wide. On 4.6+ this reparses every `.gd` file, so it is not cheap. |
| `gdscript_references_in_file` | Occurrences within one file. Much cheaper. Godot 4.7+. |
| `gdscript_hover` | Type information and documentation for a symbol. |
| `gdscript_symbols` | The symbol tree of a file. |
| `gdscript_signature_help` | Parameter info at a call site. |
| `gdscript_symbols_batch`, `gdscript_definitions_batch`, `gdscript_references_batch` | The same, across many files or positions in one call. |

### Writing code

| Tool | Description |
|------|-------------|
| `gdscript_engine_api` | Signatures and docs for an engine class or member, from the exact build in use, including members inherited from parent classes. Use instead of recalling Godot's API. |
| `gdscript_complete` | Completions at a position. The only **scene-aware** query: includes real `$NodePath` entries and the signals actually on the owning node. |
| `gdscript_validate` | Check proposed content for errors **without writing it to disk**. |
| `gdscript_rename` | Rename a symbol. Refuses when Godot will not rename it, and warns when the name also appears in scene files it cannot update. |

### Keeping Godot in step

| Tool | Description |
|------|-------------|
| `gdscript_sync_file` | Sync one modified file and return its diagnostics. Waits briefly for a new `class_name` the editor has not registered yet. |
| `gdscript_sync_files` | Sync several at once. |
| `gdscript_releas