Godotlens MCP

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.