godotlens-mcp
GodotLens is an MCP server that lets an AI agent ask Godot itself about a GDScript project — via the editor's language server, the engine, the debug adapter, and games it runs — so code edits can be understood, validated, and verified against real engine behaviour.
Navigate and understand code (
gdscript_*LSP queries): locate a declaration by name (gdscript_find), jump to definitions, list project-wide or single-file references, hover for types/docs, dump a file's symbol tree, and get call-site signature help — plus batch variants across many files/positions.Write code correctly: pull real engine API signatures and docs from the exact build in use (
gdscript_engine_api), get scene-aware completions including real$NodePaths and signals on the owning node, and check proposed file content for errors without writing it to disk (gdscript_validate).Rename safely: rename a symbol project-wide via workspace edits, optionally scanning
.tscn/.tresfor references Godot itself can't update, and preview impact with references first.Keep Godot's analysis in step: sync one or many modified
.gdfiles (optionally passing content), release a file back to disk, read compiler errors/warnings, and check connection status.Inspect project and scenes through the engine: read resolved project config (autoload singletons, input action names,
class_nameglobals, main scene) — the bare strings nothing else validates — and validate scenes for stale/dangling signal connections, missing handlers, wrong argument counts, bad node types and scripts.Debug a running game from the editor: run the project and collect its output and errors, set breakpoints, get stack traces, inspect locals/members/globals per frame, evaluate expressions at a breakpoint, and pause/continue/step-over/terminate, with status checks.
Launch and drive games (
runtime_*, per the README): start games headless (several at once, no editor needed), read output and errors, view the live scene tree, inspect and set properties, evaluate expressions, press inputs, reload changed scripts, take screenshots, read performance monitors, and time-scale/step/pause — closing the edit-run-observe-fix loop.Know the limits: LSP sees only
.gdfiles (not.tscnwiring); new files arrive only via the editor's filesystem scan; screenshots need a windowed game; hot reload covers scripts but not scenes/assets; and results carry averifiedflag where it matters.
GodotLens: Godot's own view of your GDScript project
An MCP server that lets an AI agent ask Godot itself about your project — where a symbol is used, what a method's real signature is, whether an edit compiles, how a scene is wired — and run the game, look at it and drive it, so the agent can check that the game does what it meant without a person playing it.
Why
An agent editing GDScript from text alone is guessing. It cannot tell a call from a comment,
cannot know which methods exist on a CharacterBody2D in your Godot version, cannot see that
a signal handler is wired by name inside a .tscn, and cannot see what happened at runtime.
GodotLens never answers those questions itself. It asks the engine and returns the engine's
answer. Measured on Godot 4.7.1, in a project where take_damage is defined in player.gd,
called twice from enemy.gd, once from player.gd, and named in a comment:
Approach | Result |
| 5 matches, including the comment |
| exactly 4 real call sites; the comment is not among them |
That principle — delegate every judgement to Godot — is what makes the answers trustworthy,
and it is why the tool names tell you where an answer came from. gdscript_* is the language
server. scene_* and project_* run the engine on the project. debug_* is your editor's
debugger. runtime_* is a game GodotLens launched and is connected to.
Related MCP server: Godot MCP Server
Requirements
Needed for | |
Godot 4.6+ editor open on your project |
|
A Godot binary via |
|
Python 3.10+, or Node.js 16+ for | running this server |
Godot 4.6 is the floor because the language server changed materially at 4.5 (URI encoding) and 4.6 (document ownership). Older versions are refused with a clear message rather than silently misread.
Install
npx (recommended). The package bundles the server; there are no runtime dependencies.
{
"mcpServers": {
"godotlens": {
"command": "npx",
"args": ["-y", "godotlens-mcp"]
}
}
}pip
pip install godotlens-mcp{
"mcpServers": {
"godotlens": { "command": "godotlens-mcp" }
}
}How to run
Setup | What works | Do this |
Your editor is open — normal development | Everything | Turn on Import Resources When Unfocused in Editor Settings (below). |
No editor — CI, scripts |
| For |
Games GodotLens launches ( |
| Nothing. Each game is its own process connected to GodotLens; no editor run slot is used. |
Import Resources When Unfocused. The editor notices new and changed files only when its
window gains focus. An agent-driven editor never gains focus, so a new class_name script stays
unknown — every script using it reports the name as undeclared and the game fails to parse —
and new assets stay unimported. With this setting on, the editor rescans every half second.
It is interface/editor/behavior/import_resources_when_unfocused in 4.7 and
interface/editor/import_resources_when_unfocused in 4.6; to set it for one project only, put
the 4.6 name under [editor_overrides] in project.godot (4.7 migrates it on load). When a
synced file names a class the editor has not registered, gdscript_sync_file waits briefly,
then says which class and points here.
Games GodotLens launches. runtime_run starts the game with --remote-debug pointing at
GodotLens, so the game connects to GodotLens the way it would to the editor's debugger. Games
are headless by default — no window, no sound, nothing takes focus. Pass windowed: true
only for runtime_screenshot: the window opens at a far-off position with audio muted, and is
then moved fully off-screen, so at most a small corner may show for a moment.
Script errors are reported and never stop the game. A game started this way ends when it is
stopped, when GodotLens exits, and on Windows even if GodotLens is killed outright. Its log,
like that of every engine run GodotLens starts, goes to a temporary file of its own: Godot keeps
only the newest five logs per project, and your own play and test logs stay among them.
The helper. runtime_eval and runtime_input need code inside the game. GodotLens passes
its own helper.gd to the game with --script for that run only; nothing is written to your
project. Godot still loads your project's settings, input map and autoloads, and the helper
opens the scene. A project that sets its own main loop type runs without it, and
runtime_run with helper: false runs the game exactly as it is.
Several agents. Subagents in one Claude Code session share one GodotLens process
(gdscript_status and runtime_status report its server_pid). Calls run concurrently, so a
long runtime_run or scene check does not hold up anyone else's query, and each agent can run
its own game with runtime_run (GODOT_RUNTIME_MAX_SESSIONS, default 4). Two things are not
coordinated: debug_run uses your editor's single run slot, so a second run stops the first;
and two agents writing the same file overwrite each other — have one agent write at a time.
The loop
The tools are designed around one cycle. Read it once and the rest of this document is a reference.
flowchart LR
U["<b>Understand</b><br/>gdscript_find<br/>gdscript_references<br/>gdscript_hover"]
W["<b>Write</b><br/>gdscript_engine_api<br/>gdscript_complete<br/>gdscript_validate"]
S["<b>Sync</b><br/>gdscript_sync_file"]
V["<b>Verify</b><br/>gdscript_diagnostics<br/>scene_validate<br/>project_validate"]
R["<b>Run</b><br/>runtime_run"]
O["<b>Observe & act</b><br/>runtime_tree · runtime_inspect<br/>runtime_output · runtime_eval<br/>runtime_input · runtime_screenshot"]
U --> W --> S --> V --> R --> O
O -- "fix, then runtime_reload" --> W
O -- "something is wrong" --> U
classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
class U,W,S,V,R,O step;Understand.
gdscript_findlocates a symbol by name;gdscript_referencesandgdscript_hoverexplain how it is used and what type it is.Write.
gdscript_engine_apigives real signatures instead of recalled ones,gdscript_completeoffers scene-aware candidates, andgdscript_validatechecks proposed content before it reaches disk.Sync. Godot's language server does not watch the filesystem. After editing a
.gdfile, callgdscript_sync_fileor it keeps answering from the old text.Verify.
gdscript_diagnosticsfor compile errors,scene_validatefor what the compiler cannot see in a scene,project_validateafter moving files.Run.
runtime_runstarts the game and returns its first output and errors.Observe and act. See the live tree and values, press inputs, evaluate expressions, take a screenshot; fix the code and
runtime_reloadit into the running game.
Two conventions apply throughout:
All line and character parameters are 0-indexed, matching the LSP. Editor line 1 is line 0.
gdscript_findexists partly so you rarely have to compute one by hand.Results carry a
verifiedflag where it matters.verified: falsewith an empty diagnostics list means Godot never reported back — that is not a clean bill of health.
Tools
Understanding code
Tool | Description |
| Locate a declaration by name. Returns a position the tools below accept directly. |
| Where a symbol is defined. |
| Every reference project-wide. On 4.6+ this reparses every |
| Occurrences within one file. Much cheaper. Godot 4.7+. |
| Type information and documentation for a symbol. |
| The symbol tree of a file. |
| Parameter info at a call site. |
| The same, across many files or positions in one call. |
Writing code
Tool | Description |
| Signatures and docs for an engine class or member, from the exact build in use, including members inherited from parent classes. Use instead of recalling Godot's API. |
| Completions at a position. The only scene-aware query: includes real |
| Check proposed content for errors without writing it to disk. |
| Rename a symbol. Refuses when Godot will not rename it, and warns when the name also appears in scene files it cannot update. |
Keeping Godot in step
Tool | Description |
| Sync one modified file and return its diagnostics. Waits briefly for a new |
| Sync several at once. |
| Release a file so the language server reads from disk again. |
| Errors and warnings for one or more files. |
| Connection check. Start here if anything behaves oddly. |
Project and scenes
These run the Godot binary, so scenes resolve exactly as the engine builds them, inherited and
instanced scenes included. They do not parse .tscn as text, and need no editor.
Tool | Description |
| Autoload singletons, input action names, |
| References that no longer resolve after files move: scene and resource dependencies, autoload scripts, the main scene. A reference whose UID still resolves is not broken. |
| Node tree, types, script attachments, |
| What Godot gets silently wrong in a scene. Errors: dangling connections, missing signals, handlers taking the wrong number of arguments, unknown node types, scripts that do not fit their node, missing parents, duplicate names. Warnings: unknown properties, wrong value types, NodePaths to nodes not in the scene. |
Debugger in your editor
Godot serves a Debug Adapter Protocol server from the editor, no addon required. These use the editor's own run slot — one game at a time — and are the way to set breakpoints.
Tool | Description |
| Run the project from the editor and return what it printed and every structured error. |
| Output from that game — |
| Set breakpoints in a file. |
| The call stack where execution is paused. Empty means not paused. |
| Variables in a stack frame, by scope. |
| Evaluate an expression at a breakpoint. Refused where Godot would resume the game instead of answering. |
| Execution control. |
| Stop the running game. |
| Adapter connection and whether the game is running or paused. |
Games GodotLens launches
runtime_run starts the game as its own process, connected straight back to GodotLens, so
several agents can each run one at once and no editor is needed.
Tool | Description |
| Launch the game, headless by default. Returns a session id and its first output and errors. |
| What the game printed and every structured error it raised, with file, line and stack. |
| The live scene tree, including nodes created at runtime. |
| Current property values of a node, script variables included. |
| Change a property and read it back; values are converted to the property's type. |
| Evaluate an expression while the game runs, against the scene, autoloads, engine singletons and |
| Press an input action as a player would; |
| Hot-reload changed scripts, keeping state. Refuses scripts that do not compile. |
| What a windowed game is drawing, as an image. |
| FPS, frame times, node and orphan counts, memory, custom monitors, with history. |
| Freeze, slow down, or step a game. |
| List and stop the games GodotLens is running. |
Limitations
Worth knowing before you trust a result.
What the language server cannot see
It reads
.gdfiles only. A signal handler wired in a.tscn[connection]block is invisible to it, so renaming that handler leaves the scene pointing at a method that no longer exists. This is whyscene_validateexists and whygdscript_renamewarns.Autoload and input action names are bare strings.
GameState.add_score(1)andInput.is_action_pressed("jump")are validated by nothing at all. Check them againstproject_configbefore writing them.New files reach it only through the editor's filesystem scan (see How to run). The scan notices a folder only when its modification time changes, and Godot keeps those times in whole seconds, so a file created in the same second as a scan can be missed. When a new class is still unknown a second later, GodotLens creates and removes an empty hidden file (
.godotlens-rescan) in that folder — the editor ignores dot-names — so the next scan re-reads it. Nothing else is written to your project.gdscript_referencesis expensive on 4.6+, reparsing every script in the project. Prefergdscript_references_in_filewhen one file is enough.
Running games
No pixels in a headless game.
runtime_screenshotneedswindowed: true, andruntime_stepdoes too: Godot pauses again only after the next drawn frame.Hot reload covers scripts only. Edited
.tscnfiles and new or changed assets need a restart. A script that fails to compile is disabled in the running game, soruntime_reloadrefuses one with errors — which needs the editor's language server to check; without an editor it reloads unchecked and says so.runtime_evalis Godot'sExpression, not full GDScript: calls, operators and member access, no statements or assignment. Calls run for real.Breakpoints are only in your editor (
debug_*).debug_evaluateworks only while paused in a frame with a script instance; in a static function or at a parse-error break it is refused, because Godot would resume the game instead of answering.Godot rate-limits what a game reports (
network/limits/debugger/*project settings): a game printing heavily has its output truncated by the engine.On Linux and macOS a game is stopped when GodotLens exits normally, but keeps running if GodotLens is killed outright. On Windows it is stopped either way (a job object).
Scene and project checks
scene_*andproject_configstart your autoloads, as the game would, so a script that uses an autoload compiles.project_validateandruntime_monitorsstart nothing.Some scene mistakes are not visible to any engine API. An unknown property on a
[sub_resource]is dropped by Godot while loading, before anything can ask about it.project_validatecovers scenes and resources. A brokenpreload()orextendspath in a script is a compile error, whichgdscript_diagnosticsreports.
One project, one editor. A second editor on the same project — a headless one beside your
GUI editor, say — rewrites .godot/'s class cache from its own view and can drop classes the
other registered. Attach GodotLens to the editor you have open.
Architecture
Four channels, one process. Each tool group maps to exactly one of them, which is how you know where an answer came from.
flowchart TD
Agent["AI Agent<br/>(and its subagents)"]
GL["<b>GodotLens</b><br/>MCP server · JSON-RPC 2.0<br/>Python 3.10+ · no dependencies"]
Agent <-- "stdio" --> GL
GL -- "TCP 6005<br/>language server" --> Editor
GL -- "TCP 6006<br/>debug adapter" --> Editor
GL -- "subprocess<br/>--headless --script" --> Binary
Game -- "TCP, game connects back<br/>remote debugger protocol" --> GL
Editor["<b>Godot Editor</b><br/>your open editor<br/><i>gdscript_* · debug_*</i>"]
Binary["<b>Godot binary</b><br/>run on demand<br/><i>scene_* · project_*</i>"]
Game["<b>Games GodotLens launched</b><br/>one process each<br/><i>runtime_*</i>"]
classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;
classDef godot fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;
class Agent,GL svc;
class Editor,Binary,Game godot;The MCP, LSP and DAP protocols and Godot's binary value format are implemented directly against
the standard library, so the package has zero runtime dependencies and the npm bundle is a
handful of .py and .gd files.
Configuration
Variable | Default | Description |
|
| Language server host |
|
| Language server port. The official VS Code extension uses |
|
| Debug adapter host |
|
| Debug adapter port, used by |
| auto | Godot executable, required by |
| auto | Project root; auto-detected by walking up for |
|
| Seconds to wait for a single language server response |
|
| Seconds to wait for diagnostics after a sync |
| auto | Override capability detection |
|
| Max files |
|
| Max games |
Contributing
pip install -e ".[dev]"
pytest -m "not integration" # no Godot needed
ruff check .Integration tests launch a real headless Godot and skip cleanly without one. The one test that opens a game window runs only when asked, or under a virtual display on Linux:
GODOT_BIN=/path/to/godot pytest -m integration
GODOTLENS_WINDOWED_TESTS=1 GODOT_BIN=/path/to/godot pytest -m windowedCI runs the suite on Linux, Windows and macOS across Python 3.10–3.13, runs the integration tests against a real Godot on all three, and installs the built npm tarball and executes it.
License
Available Tools
49 toolsdebug_continueB
Resume a paused game. Returns: confirmation.
Inputs: thread_id.
debug_evaluateARead-only
Evaluate a GDScript expression in the context of a paused frame. Returns: the resulting value and its type. Use to check state at a breakpoint without adding print() calls and re-running.
Inputs: expression (required), frame_id.
debug_inspectARead-only
Inspect variables visible in a stack frame. Returns: each scope (locals, members, globals) with its variables, values and types. Use the frame_id from debug_stack_trace. Only meaningful while execution is paused.
Inputs: frame_id (required).
debug_outputARead-only
Read what a game started with debug_run produced: print() output and stdout/stderr lines, plus structured errors - push_error, push_warning, engine errors and runtime script errors - each with file, function, ZERO-BASED line and call stack. Returns: lines, errors, and their counts. THIS IS THE ONLY WAY to see what the game actually did; the language server reports whether code compiles, not what it printed. Output and errors are drained on each call, so successive calls return only what is new.
Inputs: wait, clear.
debug_pauseA
Pause the running game. Returns: where it stopped. Use to inspect state at an arbitrary moment rather than a preset breakpoint.
Inputs: thread_id.
debug_runA
Run the project from the open Godot editor and collect what it prints. Returns: captured output, structured errors with call stacks, whether the game exited, and any stop reason. THIS CLOSES THE LOOP: edit, sync, run, and read the actual behaviour, without the developer pressing F5 or pasting console output back. The editor has ONE run slot: a second debug_run stops the first game. Set breakpoints with debug_set_breakpoints BEFORE calling this if you want execution to pause. Long-running games keep going - use debug_output to keep reading and debug_terminate to stop.
Inputs: args, scene, collect, timeout.
debug_set_breakpointsAIdempotent
Set breakpoints in a GDScript file, replacing any previously set in that file. Returns: each breakpoint with whether Godot verified it and the line it bound to. IMPORTANT: lines are ZERO-BASED, matching every other tool here. Set these before running the game, then use debug_stack_trace and debug_inspect once execution stops.
Inputs: file (required), lines (required).
debug_stack_traceARead-only
Get the call stack where execution is currently paused. Returns: frames with function name, file and ZERO-BASED line, plus why it stopped. An empty frame list means execution is not paused - frames exist only while stopped at a breakpoint or a runtime error.
Inputs: thread_id.
debug_statusARead-only
Check the connection to Godot's debug adapter and report whether the game is running, paused, or finished. The adapter is served by the Godot editor on port 6006 and needs no addon. Use this first if any debug_* tool behaves unexpectedly.
Inputs: no named parameters.
debug_step_overA
Step over one line in the paused game. Returns: the new stop location.
Inputs: thread_id.
debug_terminateBDestructiveIdempotent
Stop the running game. Returns: confirmation.
Inputs: no named parameters.
gdscript_completeARead-only
Get valid completions at a cursor position, from Godot's own completion engine. Returns: candidate labels with kind and detail. IMPORTANT: Uses ZERO-BASED coordinates. This is the only SCENE-AWARE query available: Godot resolves the scene that owns this script and completes against the real node, so $NodePath entries and the signals actually present on that node are included. No analysis of the .gd file alone can reproduce that.
Inputs: file (required), line (required), character (required), limit.
gdscript_definitionARead-only
Navigate to the definition of a symbol at a given position. Returns: file path and line number where the symbol is defined. IMPORTANT: Uses ZERO-BASED coordinates (editor line 1 = pass line 0). Use when you need to find where a function, variable, or class is defined.
Inputs: file (required), line (required), character (required).
gdscript_definitions_batchARead-only
Get definitions for multiple symbol positions in a single call. Returns: list of definition locations for each position. IMPORTANT: Uses ZERO-BASED coordinates. More efficient than calling gdscript_definition repeatedly.
Inputs: positions (required).
gdscript_diagnosticsARead-only
Get compiler errors and warnings for one or more files. Returns: list of diagnostics with line, severity (1=Error, 2=Warning, 3=Info, 4=Hint), and message. WORKFLOW: (1) Edit files, (2) gdscript_sync_files to refresh, (3) gdscript_diagnostics to check for errors. Use before committing to catch issues early.
Inputs: files (required).
gdscript_engine_apiARead-only
Get authoritative documentation for a Godot ENGINE class or member, from the exact editor build in use. Returns: signature with argument names, types and defaults, plus documentation. USE THIS instead of recalling Godot's API from memory - it is the ground truth for the user's version and prevents inventing methods that do not exist. Pass 'member' for a specific method/property/signal; omit it to check a class exists.
Inputs: class_name (required), member.
gdscript_findARead-only
Find where a symbol is declared BY NAME, without needing its position. Returns: declaration sites with file, ZERO-BASED line and character, kind, and containing class. USE THIS FIRST when you know a name but not its location - the returned line/character feed directly into gdscript_references, gdscript_hover and gdscript_rename. Guessing a character offset and landing one column off returns an empty result that looks identical to 'no such symbol'. Positions come from the language server, not from text matching.
Inputs: name (required), file, max_files, include_references.
gdscript_hoverARead-only
Get type information and documentation for a symbol at a given position. Returns: type signature, documentation string, or description of the symbol. IMPORTANT: Uses ZERO-BASED coordinates. Use to understand what type a variable is, or what a function returns.
Inputs: file (required), line (required), character (required).
gdscript_referencesARead-only
Find all references to a symbol across the entire project. Returns: list of locations (file, line, character) where the symbol is used. IMPORTANT: Uses ZERO-BASED coordinates. Essential for impact analysis before refactoring: 'What code uses this symbol?'
Inputs: file (required), line (required), character (required).
gdscript_references_batchARead-only
Find references for multiple symbols in a single call. Returns: list of reference locations for each position. IMPORTANT: Uses ZERO-BASED coordinates. More efficient than calling gdscript_references repeatedly. Use for bulk impact analysis across multiple symbols.
Inputs: positions (required).
gdscript_references_in_fileARead-only
Find occurrences of a symbol within ONE file. Returns: list of line/char positions. IMPORTANT: Uses ZERO-BASED coordinates. Much cheaper than gdscript_references, which reparses every .gd file in the project on Godot 4.6+. Requires Godot 4.7+; reports unsupported otherwise.
Inputs: file (required), line (required), character (required).
gdscript_release_fileAIdempotent
Release a file from the LSP session, so Godot stops serving the copy this session opened and reads from disk again. Returns: whether the file was open, and what was actually done. WHEN TO CALL: after deleting a .gd file, or when you want the LSP to forget content you synced earlier. NOTE: Godot removed its file-deletion notification in 4.6, so this cannot purge project-wide state; that clears when the editor rescans.
Inputs: file (required).
gdscript_renameARead-onlyIdempotent
Rename a symbol across all files in the project. Returns: workspace edit with all changes needed. IMPORTANT: Uses ZERO-BASED coordinates. WORKFLOW: (1) gdscript_references to preview impact, (2) gdscript_rename to rename, (3) gdscript_sync_files to refresh LSP state.
Inputs: file (required), line (required), new_name (required), character (required), +1 more.
gdscript_signature_helpARead-only
Get function signature and parameter information at a call site. Returns: function name, parameters with types, and return type. IMPORTANT: Uses ZERO-BASED coordinates. Use when you need to know the correct parameters for a function call.
Inputs: file (required), line (required), character (required).
gdscript_statusARead-only
Check connection status to the Godot LSP server. Returns: connection status, host, and port. Use this to verify Godot editor is running before using other tools. If disconnected, start Godot editor with your project open.
Inputs: no named parameters.
gdscript_symbolsARead-only
List all symbols (classes, functions, variables, signals, enums) in a file. Returns: symbol tree with name, kind, and line number for each symbol. Use to understand the structure of a file before making changes. WORKFLOW: gdscript_symbols to explore, then gdscript_hover or gdscript_definition for details.
Inputs: file (required).
gdscript_symbols_batchARead-only
Get symbols from multiple files in a single call. Returns: map of file path to symbol tree for each file. More efficient than calling gdscript_symbols repeatedly. Use to understand the structure of multiple files at once.
Inputs: files (required).
gdscript_sync_fileAIdempotent
Notify Godot's LSP that a file was modified and get updated diagnostics. Returns: diagnostics (errors/warnings) for the synced file. WHEN TO CALL: After using Edit/Write tools to modify a .gd file. The LSP does not watch files, so you must call this to refresh analysis. Optionally pass content directly to avoid reading from disk.
Inputs: file (required), content.
gdscript_sync_filesAIdempotent
Batch sync multiple modified files with Godot's LSP. Returns: diagnostics for all synced files. WHEN TO CALL: After modifying multiple .gd files with Edit/Write tools. More efficient than calling gdscript_sync_file repeatedly. Reads content from disk for all specified files.
Inputs: files (required).
gdscript_validateARead-only
Check proposed file content for errors WITHOUT writing it to disk. Returns: valid flag, errors and warnings. WHEN TO CALL: before writing an edit, so broken code never reaches the project. The LSP is restored to the on-disk content afterwards.
Inputs: file (required), content (required).
project_configARead-only
Get the project's resolved configuration: autoload singletons, input action names, class_name globals, and the main scene. Autoload and input action names are BARE STRINGS at the point of use - GameState.add_score(1), Input.is_action_pressed("jump") - and nothing validates them. Neither the compiler nor the language server catches a typo; it is a silent runtime no-op. Check names here before writing them. Values come from ProjectSettings via the engine, so defaults and feature-tagged overrides resolve correctly. Requires a Godot binary.
Inputs: no named parameters.
project_validateARead-only
Find references that no longer resolve, project-wide: scene and resource dependencies pointing at moved or deleted files, missing autoload scripts, and a missing main scene. Returns: broken references with the file that holds each, plus stale UIDs (Godot falls back to the text path and warns). WHEN TO CALL: after moving, renaming or deleting files. Nothing else reports these until the reference is loaded at runtime. Uses the engine's own resolution: a reference whose UID still resolves is not broken. Script preload()/extends paths are compile errors - gdscript_diagnostics reports them. Requires a Godot binary; runs no project code.
Inputs: no named parameters.
runtime_evalA
Evaluate an expression in a running game, while it runs - no breakpoint needed. Uses Godot's Expression: calls, operators, member access and constructors, no statements or assignment. Names available: the base node's members (default the current scene), autoloads, engine singletons such as Input, and class_name globals. Calls run for real and may change the game. Returns: the value, or the engine's error text.
Inputs: expression (required), node, session_id.
runtime_inputA
Press an input action in a running game, as a player would: pressed for the given number of frames, then released, through the normal input path, so is_action_just_pressed and _unhandled_input see it. Actions come from the project's Input Map (project_config lists them). Returns: once released.
Inputs: action (required), frames, strength, session_id.
runtime_inspectBRead-only
Current property values of one node or object in a running game, as the engine reports them. Returns: class and each property's type and value.
Inputs: node, object_id, properties, session_id.
runtime_monitorsARead-only
Performance monitors of a running game, about once a second: FPS, frame times, object, node and orphan-node counts, memory, draw calls, physics, plus any custom monitors the game registers. Returns: latest values, and a history of the requested monitors - a rising orphan count is the usual sign of a leak.
Inputs: names, session_id.
runtime_outputARead-only
Read what a running game printed and every structured error it reported since the last call - push_error, push_warning, engine and script errors, each with file, function, ZERO-BASED line and call stack. Drained on each call.
Inputs: wait, session_id.
runtime_pauseB
Freeze or unfreeze a running game's scene tree. Returns: the new state.
Inputs: paused (required), session_id.
runtime_reloadA
Hot-reload changed scripts into a running game, keeping its state. Refuses when the language server reports errors in them: a script that fails to compile is disabled in the running game. Covers .gd scripts only - edited .tscn files and new or changed assets need a restart.
Inputs: files (required), session_id.
runtime_runA
Launch the game as its own process, connected straight back to GodotLens - no editor run slot, so several agents can each run one at once. Returns: session_id, and the output and structured errors from the first seconds. Runs HEADLESS by default (no window, no sound); pass windowed=true only when you need runtime_screenshot - the window is placed off-screen and takes no focus. Script errors are reported, never stop the game. Then use runtime_tree, runtime_inspect and runtime_output to see what the game is doing. The game runs through GodotLens's helper (loaded for this run only, nothing is written to the project), which adds runtime_eval and runtime_input.
Inputs: args, scene, helper, collect, +3 more.
runtime_screenshotARead-only
Capture what a windowed game is drawing. Returns: the image, with its size. Needs a session started with windowed=true; a headless game has no pixels.
Inputs: session_id.
runtime_setA
Change a property on a node in a running game, then read it back. Values are converted to the property's own type: pass [1, 2] or 'Vector2(1, 2)' for a Vector2, '#ff0000' for a Color, a res:// path for a resource. Returns: the value the engine now reports.
Inputs: value (required), property (required), node, object_id, +1 more.
runtime_statusARead-only
List the games GodotLens is running. Returns: each session with pid, scene, whether it is headless, running and connected, plus this server's pid.
Inputs: no named parameters.
runtime_stepA
Advance a paused game by one frame. Windowed sessions only: a headless game never draws a frame, and Godot re-pauses after the next drawn frame.
Inputs: session_id.
runtime_stopADestructive
Stop a game started with runtime_run. Returns: exit code.
Inputs: session_id.
runtime_time_scaleB
Speed up or slow down a running game. Returns: the new scale.
Inputs: scale (required), session_id.
runtime_treeARead-only
The live scene tree of a running game, including nodes created at runtime. Returns: nested nodes with name, type (script class_name or path when scripted), path, object_id and visibility. Use the path or object_id with runtime_inspect.
Inputs: path, max_depth, session_id.
scene_stateARead-only
Get Godot's own resolved view of a scene: node tree with types, script attachments, unique_name_in_owner flags, exported property values, and the signal connections declared in the scene. Godot's LSP reads .gd files only, so NONE of this is visible to gdscript_references or gdscript_rename. Runs the engine to resolve the scene, so inherited scenes and instanced children are resolved the way Godot actually instantiates them. Requires a Godot binary (GODOT_BIN or ./godot/).
Inputs: files (required).
scene_validateARead-only
Check a scene for what Godot gets silently wrong when it loads or runs it. Errors: connections to handlers or nodes that do not exist, signals the source does not have, handlers taking the wrong number of arguments, unknown node types, scripts whose base type does not fit the node, missing parents, duplicate names and duplicate unique names, and changes to nodes that do not exist in an instanced scene. Warnings: unknown properties, values of the wrong type, and NodePaths to nodes not in the scene. Returns: per-scene problems with kind, severity and detail; valid means no errors. WHEN TO CALL: after editing a .tscn, or after renaming or removing a signal handler in GDScript. Godot accepts all of these with no error or only a console warning. Facts come from the engine; handler existence from the LSP's parse of the attached script.
Inputs: files (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Two large families overlap heavily: debug_run/debug_output/debug_pause/debug_step_over/debug_inspect/debug_evaluate/debug_terminate mirror runtime_run/runtime_output/runtime_pause/runtime_step/runtime_inspect/runtime_eval/runtime_stop, and gdscript_references vs gdscript_references_in_file vs gdscript_references_batch, or gdscript_sync_file(s) vs gdscript_diagnostics, blur together. The descriptions do carefully explain the distinction (editor run slot vs separate process, breakpoint vs live, single vs batch), so an attentive agent can choose correctly, but the boundaries are not self-evident from names alone.
Names use a predictable snake_case namespace_verb/noun pattern with clean subsystem prefixes (gdscript_, debug_, runtime_, project_, scene_), and plural suffixes cleanly mark batch variants. Minor deviation: within families the second token mixes verbs and nouns (gdscript_complete vs gdscript_status vs gdscript_find), but this stays readable and consistent overall.
At 49 tools this is far past the comfortable range, and much of the bulk comes from parallel variants rather than distinct capabilities (three _batch wrappers, _sync_file vs _sync_files, references vs references_in_file, two near-identical run/inspect/output stacks). The breadth of the domain (LSP, debug adapter, standalone runtime, scene, project) explains some of it, but the surface is heavy enough that tool selection becomes a real burden.
Coverage is unusually strong end to end: navigation, hover, signature help, rename, validation-without-write, diagnostics, engine API lookup, project/scene validation, and both breakpoint debugging and live runtime introspection. Minor gaps remain, such as no workspace-wide symbol search and no hot-reload path for edited .tscn files or new assets (runtime_reload is GDScript-only), but these are workaround-able.
Maintenance
Related MCP Connectors
The official Svelte MCP server providing docs and autofixing tools for Svelte development
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides instant GDScript syntax validation and diagnostics by bridging Godot's native Language Server Protocol to MCP clients. Enables real-time syntax checking in AI assistants without requiring custom plugins or context switching to the Godot editor.496 npm47MIT
- FlicenseAqualityDmaintenanceAn MCP server that provides tools for Godot Engine development, enabling users to run unit tests, check for syntax errors, and manage project scenes or exports.52-
- AlicenseBqualityDmaintenanceAn MCP server for Godot game development that provides 45 tools for reading, analyzing, and editing projects. It enables users to manage scene trees, navigate GDScript symbols, and interact with the Godot runtime for debugging and state capture.52MIT
- AlicenseAqualityFmaintenanceA Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation via stdio and optional WebSocket bridge.389MIT