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 if Godot LSP is connected |

Navigation (6 tools)

| Tool | Description | |------|-------------| | gdscript_definition | Go to definition of a symbol | | gdscript_declaration | Go to declaration of a symbol | | gdscript_references | Find all references to a symbol | | gdscript_hover | Get hover information (type, docs) for a symbol | | gdscript_symbols | List all symbols in a file | | gdscript_signature_help | Get function signature at call site |

Refactoring

| Tool | Description | |------|-------------| | gdscript_rename | Rename a symbol across all files |

Synchronization (3 tools)

| Tool | Description | |------|-------------| | gdscript_sync_file | Notify LSP that a file changed, returns diagnostics | | gdscript_sync_files | Batch sync multiple files | | gdscript_delete_file | Notify LSP that a file was deleted |

Batch Operations (3 tools)

| Tool | Description | |------|-------------| | gdscript_symbols_batch | Get symbols from multiple files | | gdscript_definitions_batch | Get definitions for multiple positions | | gdscript_references_batch | Find references for multiple positions |

Diagnostics

| Tool | Description | |------|-------------| | gdscript_diagnostics | Get errors/warnings for files |

Architecture

┌──────────────┐         ┌────────────────────┐         ┌───────────────────┐
│   AI Agent   │  stdio  │  GodotLens (MCP)   │   TCP   │  Godot Editor     │
│ (Claude, etc)├────────►│  J

... [View full README on GitHub](https://github.com/pzalutski-pixel/godotlens-mcp#readme)