pzalutski-pixel/godotlens-mcp

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 what the game actually printed when it ran.
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_config run the engine. debug_* is the debugger.
Requirements
| | Needed for |
|---|---|
| **Godot 4.6+** with your project open | everything — the language server and debug adapter live inside the editor |
| **Python 3.10+**, or **Node.js 16+** for npx | running this server |
| A Godot **binary** via GODOT_BIN, a ./godot/ directory, or PATH | scene_* and project_config, which invoke the engine |
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.
The editor does not need a visible window — this is what CI uses:
Install
**npx** (recommended). The package bundles the server; there are no runtime dependencies.
**pip**
The loop
The tools are designed around one cycle. Read it once and the rest of this document is a
reference.
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 the wiring the
compiler cannot see.
5. **Run.** debug_run starts the game and returns what it printed.
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. |