# GodotLens

Connects coding agents to Godot 4.6+ to inspect GDScript, validate scene hierarchies, and drive gameplay headlessly without manual playtesting.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10
- Author: pzalutski-pixel
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pzalutski-pixel/godotlens-mcp
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/mcp/godotlens

## What it does

GodotLens delegates project queries directly to the Godot engine rather than parsing GDScript text with search tools. Commands follow explicit namespaces: `gdscript_*` queries the editor language server, `scene_*` and `project_*` execute project validation via the engine binary, and `runtime_*` manages standalone game processes. An agent sees exact call sites, true engine method signatures, and scene signal wiring without confusing comments for code.

Full operation requires an active Godot 4.6+ editor instance or a headless editor process with LSP and DAP ports exposed. If the Import Resources When Unfocused editor setting remains disabled, Godot ignores newly created script files and `class_name` definitions because the agent-controlled window never receives window focus. For runtime evaluation, GodotLens injects a temporary helper script via command-line arguments without modifying repository files.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GODOT_LSP_HOST`, `GODOT_LSP_PORT`, `GODOT_DAP_HOST`, `GODOT_DAP_PORT`, `GODOT_BIN`, `GODOT_PROJECT_ROOT`, `GODOT_LSP_TIMEOUT`, `GODOT_DIAGNOSTICS_TIMEOUT`, `GODOT_VERSION`, `GODOT_FIND_FILE_LIMIT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Godot

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> --transport stdio godotlens -- npx -y godotlens-mcp
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add godotlens --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> -- npx -y godotlens-mcp
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "godotlens": {
            "command": "npx",
            "args": [
                "-y",
                "godotlens-mcp"
            ],
            "env": {
                "GODOT_LSP_HOST": "<GODOT_LSP_HOST>",
                "GODOT_LSP_PORT": "<GODOT_LSP_PORT>",
                "GODOT_DAP_HOST": "<GODOT_DAP_HOST>",
                "GODOT_DAP_PORT": "<GODOT_DAP_PORT>",
                "GODOT_BIN": "<GODOT_BIN>"
            }
        }
    }
}
```
Replace <…> with your own values. 6 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "godotlens": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "godotlens-mcp"
            ],
            "env": {
                "GODOT_LSP_HOST": "<GODOT_LSP_HOST>",
                "GODOT_LSP_PORT": "<GODOT_LSP_PORT>",
                "GODOT_DAP_HOST": "<GODOT_DAP_HOST>",
                "GODOT_DAP_PORT": "<GODOT_DAP_PORT>",
                "GODOT_BIN": "<GODOT_BIN>"
            }
        }
    }
}
```
Replace <…> with your own values. 6 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GODOT_LSP_HOST=<GODOT_LSP_HOST> -e GODOT_LSP_PORT=<GODOT_LSP_PORT> -e GODOT_DAP_HOST=<GODOT_DAP_HOST> -e GODOT_DAP_PORT=<GODOT_DAP_PORT> -e GODOT_BIN=<GODOT_BIN> godotlens npx -y godotlens-mcp
```
Replace <…> with your own values. 6 more environment variables are in the server README

## When to use it
- locate exact GDScript function call sites without false positives from comments
- validate scene files and signal bindings directly against engine rules
- launch headless game sessions to observe runtime behavior without manual interaction
- execute in-game expressions via `runtime_eval` without altering project assets

## Example prompts
- Find all references to the `take_damage` method across the project using `gdscript_references`
- Validate the `player.tscn` scene structure and check for broken signal links
- Start the game headlessly using `runtime_run` and inspect the active scene tree

## Similar
- [godot-gdscript-headless-testing](https://affpapa.org/en/nevibecode/skills/godot-gdscript-headless-testing.md) — skill · 3400 installs
- [godot-mcp-enhanced](https://affpapa.org/en/nevibecode/mcp/godot-mcp-enhanced.md) — MCP server · ★ 103
- [godot-camera-systems](https://affpapa.org/en/nevibecode/skills/godot-camera-systems.md) — skill · 533 installs
- [godot-2d-physics](https://affpapa.org/en/nevibecode/skills/godot-2d-physics.md) — skill · 516 installs
- [godot-mcp](https://affpapa.org/en/nevibecode/mcp/tomyud1-godot-mcp.md) — MCP server · ★ 445

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md