GodotLens: AI-First Code Analysis for GDScript
An MCP server providing 15 semantic analysis tools for GDScript, powered by Godot's built-in Language Server.
Built for AI Agents
AI coding agents work with text files but lack semantic understanding of GDScript. When an agent uses grep to find usages of a function, it cannot distinguish a function call from a comment containing the same name, a signal declaration from a signal emission, or an overridden method from an unrelated function.
GodotLens bridges this gap by exposing Godot's built-in Language Server through the Model Context Protocol (MCP), giving AI agents compiler-accurate code intelligence for GDScript — go to definition, find references, diagnostics, rename, and more.
Example: Finding all usages of _on_player_hit:
| Approach | Result |
|---|---|
grep "_on_player_hit" | 12 matches including comments, strings, and similarly named functions |
gdscript_references | Exactly 4 call sites where _on_player_hit is invoked |
Prerequisites
- Godot 4.x editor must be running with your project open — Godot's LSP server starts automatically when the editor opens a project
- Python 3.10+ (for pip install) or Node.js 16+ (for npx)
Quick Start
Option A: npx (recommended for MCP clients)
Add to your MCP configuration (e.g., .mcp.json for Claude Code):
{
"mcpServers": {
"godotlens": {
"command": "npx",
"args": ["-y", "godotlens-mcp"]
}
}
}
The npm package bundles the full server (~20 KB of Python). Zero external Python dependencies.
Option B: pip
pip install godotlens-mcp
{
"mcpServers": {
"godotlens": {
"command": "godotlens-mcp"
}
}
}
Configuration
| Environment Variable | Default | Description |
|---|---|---|
GODOT_LSP_HOST | 127.0.0.1 | Godot LSP server host |
GODOT_LSP_PORT | 6005 | Godot LSP server port |
Tools
Health
| Tool | Description |
|---|---|
gdscript_status | Check connection to Godot LSP. Use to verify editor is running before other tools. |
Navigation (6 tools)
| Tool | Description |
|---|---|
gdscript_definition | Navigate to where a symbol is defined. Returns file path and line number. |
gdscript_declaration | Navigate to the declaration site of a symbol. |
gdscript_references | Find all references to a symbol across the project. Essential for impact analysis before refactoring. |
gdscript_hover | Get type information and documentation for a symbol. Use to understand types and return values. |
gdscript_symbols | List all symbols (classes, functions, variables, signals) in a file. Use to explore file structure. |
gdscript_signature_help | Get function signature and parameter info at a call site. |
Refactoring
| Tool | Description |
|---|---|
gdscript_rename | Rename a symbol across all files. Workflow: references to preview impact, rename, then sync. |
Synchronization (3 tools)
| Tool | Description |
|---|---|
gdscript_sync_file | Sync a modified file with the LSP and get updated diagnostics. Call after editing .gd files. |
gdscript_sync_files | Batch sync multiple modified files. More efficient than syncing individually. |
gdscript_delete_file | Notify LSP a file was deleted. Clears stale diagnostics. |
Batch Operations (3 tools)
| Tool | Description |
|---|---|
gdscript_symbols_batch | Get symbols from multiple files in one call. |
gdscript_definitions_batch | Get definitions for multiple positions in one call. |
gdscript_references_batch | Find references for multiple symbols in one call. Use for bulk impact analysis. |
Diagnostics
| Tool | Description |
|---|---|
gdscript_diagnostics | Get compiler errors and warnings. Workflow: edit, sync, then diagnostics to verify. |
Architecture
┌──────────────┐ ┌────────────────────┐ ┌───────────────────┐
│ AI Agent │ stdio │ GodotLens (MCP) │ TCP │ Godot Editor │
│ (Claude, etc)├────────►│ JSON-RPC 2.0 ├────────►│ Built-in LSP │
│ │◄────────┤ Python 3.10+ │◄────────┤ Port 6005 │
└──────────────┘ └────────────────────┘ └───────────────────┘
GodotLens acts as a bridge between the AI agent and Godot's built-in Language Server. The AI agent communicates with GodotLens via MCP (JSON-RPC over stdio). GodotLens translates MCP tool calls into LSP requests and sends them to the Godot editor over TCP. Responses are compacted for efficient AI consumption.
Zero dependencies — the server uses only the Python standard library. The MCP and LSP protocols are implemented directly, keeping the server lightweight and self-contained.
Important: File Synchronization
Godot's LSP does not automatically detect file changes made outside the editor. When the AI agent modifies a .gd file, it should call gdscript_sync_file or gdscript_sync_files so the LSP re-analyzes the changed code. Without this, diagnostics and navigation results may be stale.
Recommended workflow:
- Use GodotLens tools to analyze code
- Write changes to files
- Call
gdscript_sync_fileto refresh LSP state - Use GodotLens tools to verify changes
Coordinate System
All line and character parameters are 0-indexed, matching the LSP specification:
- Line 0, Character 0 = first character of the file
License
MIT License — see LICENSE for details.
<!-- mcp-name: io.github.pzalutski-pixel/godotlens -->