godotlens-mcp

GodotLens is an MCP (Model Context Protocol) server that lets AI agents answer questions about GDScript projects through Godot's built-in language server, engine, and debugger, rather than guessing on their own. Its core principle is "leave every judgment to Godot itself," so the answers it returns are more trustworthy. The tool requires Godot 4.6 or higher (because the language server changed substantially between 4.5 and 4.6), and older versions are explicitly rejected.

Main capabilities

• Understanding code:gdscript_find look up symbols by name;gdscript_references and gdscript_hover explain how symbols are used and their types.
• Writing code:gdscript_engine_api provide real signatures rather than recalled signatures;gdscript_complete provide scene-aware completion suggestions;gdscript_validate check proposed content before writing to disk.
• Syncing files: The Godot language server does not watch the file system, so after editing a .gd file you need to call gdscript_sync_file, otherwise it will continue to answer using the old text.
• Validation:gdscript_diagnostics checks for compilation errors;scene_validate checks scene connections that the compiler cannot see.
• Running:debug_run launches the game and returns its printed output.

How to use

Installing via npx is recommended; the package has a built-in server and no runtime dependencies. Tool names indicate the source of the answer:gdscript_* comes from the language server;scene_* and project_config run the engine;debug_* comes from the debugger. All line and character parameters are 0-indexed, consistent with LSP. Results carry a verified flag at critical points; if verified: false and the diagnostics list is empty, it means Godot did not report back, and does not mean it is clean and error-free.

Applicable scenarios and limitations

Suitable for development workflows that require AI agents to accurately understand GDScript projects, avoid text-based guessing, and validate compilation and scene connections after editing. Known limitations include: the language server only reads .gd files and cannot see signal handlers connected by name in .tscn, so renaming may cause runtime failures without compilation errors; autoload and input action names are bare strings and will not be validated;gdscript_references is expensive on 4.6+, so it is recommended to prefer gdscript_references_in_file. The project is licensed under the Apache License 2.0.