# pzalutski-pixel/godotlens-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/pzalutski-pixel/godotlens-mcp  
**GitHub Stars:** 8  
**npm Downloads (last month):** 566  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pzalutski-pixel-godotlens-mcp

## Description
15 semantic GDScript analysis tools via Godot's built-in LSP. Navigation, references, diagnostics, rename, and file sync for AI agents.

## Tools
Capabilities this server exposes over MCP:

- **gdscript_status** — Check connection status to the Godot LSP server. Returns: connection status, host, and port. Use this to verify Godot editor is running before using other tools. If disconnected, start Godot editor with your project open.
- **gdscript_definition** — Navigate to the definition of a symbol at a given position. Returns: file path and line number where the symbol is defined. IMPORTANT: Uses ZERO-BASED coordinates (editor line 1 = pass line 0). Use when you need to find where a function, variable, or class is defined.
- **gdscript_references** — Find all references to a symbol across the entire project. Returns: list of locations (file, line, character) where the symbol is used. IMPORTANT: Uses ZERO-BASED coordinates. Essential for impact analysis before refactoring: 'What code uses this symbol?'
- **gdscript_hover** — Get type information and documentation for a symbol at a given position. Returns: type signature, documentation string, or description of the symbol. IMPORTANT: Uses ZERO-BASED coordinates. Use to understand what type a variable is, or what a function returns.
- **gdscript_symbols** — List all symbols (classes, functions, variables, signals, enums) in a file. Returns: symbol tree with name, kind, and line number for each symbol. Use to understand the structure of a file before making changes. WORKFLOW: gdscript_symbols to explore, then gdscript_hover or gdscript_definition for details.
- **gdscript_signature_help** — Get function signature and parameter information at a call site. Returns: function name, parameters with types, and return type. IMPORTANT: Uses ZERO-BASED coordinates. Use when you need to know the correct parameters for a function call.
- **gdscript_rename** — Rename a symbol across all files in the project. Returns: workspace edit with all changes needed. IMPORTANT: Uses ZERO-BASED coordinates. WORKFLOW: (1) gdscript_references to preview impact, (2) gdscript_rename to rename, (3) gdscript_sync_files to refresh LSP state.
- **gdscript_sync_file** — Notify Godot's LSP that a file was modified and get updated diagnostics. Returns: diagnostics (errors/warnings) for the synced file. WHEN TO CALL: After using Edit/Write tools to modify a .gd file. The LSP does not watch files, so you must call this to refresh analysis. Optionally pass content directly to avoid reading from disk.
- **gdscript_sync_files** — Batch sync multiple modified files with Godot's LSP. Returns: diagnostics for all synced files. WHEN TO CALL: After modifying multiple .gd files with Edit/Write tools. More efficient than calling gdscript_sync_file repeatedly. Reads content from disk for all specified files.
- **gdscript_release_file** — Release a file from the LSP session, so Godot stops serving the copy this session opened and reads from disk again. Returns: whether the file was open, and what was actually done. WHEN TO CALL: after deleting a .gd file, or when you want the LSP to forget content you synced earlier. NOTE: Godot removed its file-deletion notification in 4.6, so this cannot purge project-wide state; that clears when the editor rescans.
- **gdscript_symbols_batch** — Get symbols from multiple files in a single call. Returns: map of file path to symbol tree for each file. More efficient than calling gdscript_symbols repeatedly. Use to understand the structure of multiple files at once.
- **gdscript_definitions_batch** — Get definitions for multiple symbol positions in a single call. Returns: list of definition locations for each position. IMPORTANT: Uses ZERO-BASED coordinates. More efficient than calling gdscript_definition repeatedly.
- **gdscript_references_batch** — Find references for multiple symbols in a single call. Returns: list of reference locations for each position. IMPORTANT: Uses ZERO-BASED coordinates. More efficient than calling gdscript_references repeatedly. Use for bulk impact analysis across multiple symbols.
- **gdscript_diagnostics** — Get compiler errors and warnings for one or more files. Returns: list of diagnostics with line, severity (1=Error, 2=Warning, 3=Info, 4=Hint), and message. WORKFLOW: (1) Edit files, (2) gdscript_sync_files to refresh, (3) gdscript_diagnostics to check for errors. Use before committing to catch issues early.
- **gdscript_engine_api** — Get authoritative documentation for a Godot ENGINE class or member, from the exact editor build in use. Returns: signature with argument names, types and defaults, plus documentation. USE THIS instead of recalling Godot's API from memory - it is the ground truth for the user's version and prevents inventing methods that do not exist. Pass 'member' for a specific method/property/signal; omit it to check a class exists.
- **gdscript_complete** — Get valid completions at a cursor position, from Godot's own completion engine. Returns: candidate labels with kind and detail. IMPORTANT: Uses ZERO-BASED coordinates. This is the only SCENE-AWARE query available: Godot resolves the scene that owns this script and completes against the real node, so $NodePath entries and the signals actually present on that node are included. No analysis of the .gd file alone can reproduce that.
- **gdscript_validate** — Check proposed file content for errors WITHOUT writing it to disk. Returns: valid flag, errors and warnings. WHEN TO CALL: before writing an edit, so broken code never reaches the project. The LSP is restored to the on-disk content afterwards.
- **gdscript_references_in_file** — Find occurrences of a symbol within ONE file. Returns: list of line/char positions. IMPORTANT: Uses ZERO-BASED coordinates. Much cheaper than gdscript_references, which reparses every .gd file in the project on Godot 4.6+. Requires Godot 4.7+; reports unsupported otherwise.
- **scene_state** — Get Godot's own resolved view of a scene: node tree with types, script attachments, unique_name_in_owner flags, exported property values, and the signal connections declared in the scene. Godot's LSP reads .gd files only, so NONE of this is visible to gdscript_references or gdscript_rename. Runs the engine to resolve the scene, so inherited scenes and instanced children are resolved the way Godot actually instantiates them. Requires a Godot binary (GODOT_BIN or ./godot/).
- **scene_validate** — Check that a scene's signal connections still point at methods that exist. Returns: per-scene problems - missing handler methods, targets with no script, and connections aimed at nodes that are not in the scene. WHEN TO CALL: after editing a .tscn, or after renaming or removing a signal handler in GDScript. Connections are stored as unvalidated STRINGS, so a stale one produces no compile error and fails only when the signal fires at runtime. Handler existence is checked against the LSP's parse of the attached script.
- **debug_status** — Check the connection to Godot's debug adapter and report whether the game is running, paused, or finished. The adapter is served by the Godot editor on port 6006 and needs no addon. Use this first if any debug_* tool behaves unexpectedly.
- **debug_output** — Read console output the running game produced - print() calls, stdout, stderr, and runtime script errors with their source location. Returns: captured lines with category and originating file/line. THIS IS THE ONLY WAY to see what the game actually did; the language server reports whether code compiles, not what it printed. Output is drained on each call, so successive calls return only what is new.
- **debug_set_breakpoints** — Set breakpoints in a GDScript file, replacing any previously set in that file. Returns: each breakpoint with whether Godot verified it and the line it bound to. IMPORTANT: lines are ZERO-BASED, matching every other tool here. Set these before running the game, then use debug_stack_trace and debug_inspect once execution stops.
- **debug_stack_trace** — Get the call stack where execution is currently paused. Returns: frames with function name, file and ZERO-BASED line, plus why it stopped. An empty frame list means execution is not paused - frames exist only while stopped at a breakpoint or a runtime error.
- **debug_inspect** — Inspect variables visible in a stack frame. Returns: each scope (locals, members, globals) with its variables, values and types. Use the frame_id from debug_stack_trace. Only meaningful while execution is paused.
- **debug_evaluate** — Evaluate a GDScript expression in the context of a paused frame. Returns: the resulting value and its type. Use to check state at a breakpoint without adding print() calls and re-running.
- **debug_continue** — Resume a paused game. Returns: confirmation.
- **debug_pause** — Pause the running game. Returns: where it stopped. Use to inspect state at an arbitrary moment rather than a preset breakpoint.
- **debug_step_over** — Step over one line in the paused game. Returns: the new stop location.
- **debug_terminate** — Stop the running game. Returns: confirmation.
- **gdscript_find** — Find where a symbol is declared BY NAME, without needing its position. Returns: declaration sites with file, ZERO-BASED line and character, kind, and containing class. USE THIS FIRST when you know a name but not its location - the returned line/character feed directly into gdscript_references, gdscript_hover and gdscript_rename. Guessing a character offset and landing one column off returns an empty result that looks identical to 'no such symbol'. Positions come from the language server, not from text matching.
- **project_config** — Get the project's resolved configuration: autoload singletons, input action names, class_name globals, and the main scene. Autoload and input action names are BARE STRINGS at the point of use - GameState.add_score(1), Input.is_action_pressed("jump") - and nothing validates them. Neither the compiler nor the language server catches a typo; it is a silent runtime no-op. Check names here before writing them. Values come from ProjectSettings via the engine, so defaults and feature-tagged overrides resolve correctly. Requires a Godot binary.
- **debug_run** — Run the project and collect what it prints. Returns: captured stdout/stderr, whether the game exited, and any stop reason. THIS CLOSES THE LOOP: edit, sync, run, and read the actual behaviour, without the developer pressing F5 or pasting console output back. The game runs in the Godot editor that is already open. Set breakpoints with debug_set_breakpoints BEFORE calling this if you want execution to pause. Long-running games keep going - use debug_output to keep reading and debug_terminate to stop.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What pzalutski-pixel/godotlens-mcp MCP server does

pzalutski-pixel/godotlens-mcp MCP server exposes Godot's own project analysis capabilities to an AI agent. It is intended for agents that read or modify GDScript and need results grounded in the active Godot project rather than approximate text processing.

The language-server tools cover symbol definitions, references, hover information, signatures, file symbols, completions, diagnostics, and project-wide renames. Batch variants reduce repeated calls when analyzing several files or positions. The server also includes scene and runtime functions: scene inspection resolves the node tree and attached scripts as Godot instantiates them, while the debugger can report output, stack frames, variables, evaluated expressions, breakpoints, and execution state.

## How it works

Godot must be running with the project open. The server communicates with the editor's language server for `gdscript_*` operations and with the editor's debug adapter for `debug_*` operations. The language server uses zero-based line and character positions, so an editor's first line is passed as line 0.

Godot's language server does not automatically watch filesystem edits made by external tools. After changing a GDScript file, call `gdscript_sync_file` or `gdscript_sync_files`; otherwise subsequent analysis may use the older in-session content. `gdscript_release_file` lets the session discard content it previously supplied and return to the disk version.

A practical editing cycle is to inspect symbols and references, check the engine API or completions, validate proposed content, write the change, synchronize modified files, and then inspect diagnostics. For runtime issues, check the debug connection, run or pause the game, and use output or paused-frame inspection to investigate behavior.

## Setup and configuration

pzalutski-pixel/godotlens-mcp MCP server can run through Node.js 16 or newer with `npx`, or through Python 3.10 or newer after installing the package. The documented Node configuration uses `npx -y godotlens-mcp`; the Python configuration starts the `godotlens-mcp` executable.

Godot 4.6 or newer is required. Start the editor with the target project open. Headless operation is also supported using Godot's editor mode with LSP port 6005 and debug adapter port 6006. Scene operations require a Godot binary available through `GODOT_BIN`, a `./godot/` directory, or the system `PATH`.

## Tools and capabilities

- Navigate to definitions and find project-wide or file-local references.
- Read symbol trees, hover documentation, function signatures, and scene-aware completions.
- Query authoritative engine class or member documentation from the active Godot build.
- Validate proposed content without writing it, then retrieve compiler errors and warnings.
- Rename symbols and return the workspace edits needed across files.
- Synchronize one or many modified files with the language server.
- Inspect resolved scene nodes, scripts, exported values, unique-owner flags, and signal connections.
- Check scene signal connections for missing handlers, missing scripts, or invalid targets.
- Read runtime output, set breakpoints, inspect stack frames and variables, evaluate expressions, and control paused execution.

## Limitations and notes

The GDScript language server analyzes `.gd` files, so scene-defined signal connections are not covered by ordinary references or renames. Use `scene_validate` after editing scenes or changing signal handlers. The scene tools require a Godot binary, and `gdscript_references_in_file` requires Godot 4.7 or newer.

Full-project reference searches can be expensive on Godot 4.6 and newer because they reparse every GDScript file; use the file-local variant where appropriate. Runtime output is drained after each read, and stack variables or expression evaluation are meaningful only while execution is paused. A disconnected status or an empty result does not necessarily prove that a project is clean, so check the returned connection and verification information before relying on it.

pzalutski-pixel/godotlens-mcp MCP server does not replace Godot's runtime behavior with static guesses: compile diagnostics describe code validity, while the debug tools are needed to determine what the running game printed or how it stopped.

_Full upstream README: https://allmcps.com/mcp/pzalutski-pixel-godotlens-mcp/readme_