GodotLens — Claude Code MCP server: what it does, how to install
Connects coding agents to Godot 4.6+ to inspect GDScript, validate scene hierarchies, and drive gameplay headlessly without manual playtesting.
claude mcp add --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> --transport stdio godotlens -- npx -y godotlens-mcpWhat GodotLens does
GodotLens delegates project queries directly to the Godot engine rather than parsing GDScript text with search tools. Commands follow explicit namespaces: gdscript_* queries the editor language server, scene_* and project_* execute project validation via the engine binary, and runtime_* manages standalone game processes. An agent sees exact call sites, true engine method signatures, and scene signal wiring without confusing comments for code.
Full operation requires an active Godot 4.6+ editor instance or a headless editor process with LSP and DAP ports exposed. If the Import Resources When Unfocused editor setting remains disabled, Godot ignores newly created script files and class_name definitions because the agent-controlled window never receives window focus. For runtime evaluation, GodotLens injects a temporary helper script via command-line arguments without modifying repository files.
What it helps with
- locate exact GDScript function call sites without false positives from comments
- validate scene files and signal bindings directly against engine rules
- launch headless game sessions to observe runtime behavior without manual interaction
- execute in-game expressions via
runtime_evalwithout altering project assets
Example prompts for the agent
- Find all references to the
take_damagemethod across the project usinggdscript_references - Validate the
player.tscnscene structure and check for broken signal links - Start the game headlessly using
runtime_runand inspect the active scene tree
How to install GodotLens
Platform CLI
claude mcp add --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> --transport stdio godotlens -- npx -y godotlens-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
codex mcp add godotlens --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> -- npx -y godotlens-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"godotlens": {
"command": "npx",
"args": [
"-y",
"godotlens-mcp"
],
"env": {
"GODOT_LSP_HOST": "<GODOT_LSP_HOST>",
"GODOT_LSP_PORT": "<GODOT_LSP_PORT>",
"GODOT_DAP_HOST": "<GODOT_DAP_HOST>",
"GODOT_DAP_PORT": "<GODOT_DAP_PORT>",
"GODOT_BIN": "<GODOT_BIN>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"godotlens": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"godotlens-mcp"
],
"env": {
"GODOT_LSP_HOST": "<GODOT_LSP_HOST>",
"GODOT_LSP_PORT": "<GODOT_LSP_PORT>",
"GODOT_DAP_HOST": "<GODOT_DAP_HOST>",
"GODOT_DAP_PORT": "<GODOT_DAP_PORT>",
"GODOT_BIN": "<GODOT_BIN>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
gemini mcp add -e GODOT_LSP_HOST=<GODOT_LSP_HOST> -e GODOT_LSP_PORT=<GODOT_LSP_PORT> -e GODOT_DAP_HOST=<GODOT_DAP_HOST> -e GODOT_DAP_PORT=<GODOT_DAP_PORT> -e GODOT_BIN=<GODOT_BIN> godotlens npx -y godotlens-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about GodotLens
How do I install GodotLens in Claude Code?
Run claude mcp add godotlens -- npx -y godotlens-mcp in your terminal. For custom ports or binary paths, pass environment variables: `claude mcp add --env GODOT_LSP_HOST=<GODOT_LSP_HOST> --env GODOT_LSP_PORT=<GODOT_LSP_PORT> --env GODOT_DAP_HOST=<GODOT_DAP_HOST> --env GODOT_DAP_PORT=<GODOT_DAP_PORT> --env GODOT_BIN=<GODOT_BIN> --transport stdio godotlens -- npx -y godotlens-mcp`.
What does GodotLens do?
It provides an MCP interface for querying Godot's language server, inspecting scene trees, and driving game execution. Agents can verify edits against the real engine, execute test inputs, and review logs without human playtesting.
Why does GodotLens require Godot 4.6 or higher?
Godot 4.5 and 4.6 introduced critical updates to URI handling and document ownership in the built-in LSP. Earlier versions are rejected immediately to prevent silent parsing failures.
