MCP server for GDScript semantic analysis via Godot's built-in language server
概览
An MCP server that lets an AI agent ask 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. 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: 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.
README
以下为原文 README 节选，完整内容请查看原文。
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 |
|---|---|
grep take_damage |
5 matches, including the comment |
gdscript_references |
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.
Requirements
| Needed for | |
|---|---|
| Godot 4.6+ editor open on your project | gdscript_* and debug_* — the language server and debug adapter live inside the editor |
A Godot binary via GODOT_BIN, a ./godot/ directory, or PATH |
scene_*, project_* and runtime_*, which run the engine themselves and need no editor |
Python 3.10+, or Node.js 16+ for npx |
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 |
|---|
安装
npx -y godotlens-mcp配置
{
"mcpServers": {
"godotlens": {
"command": "npx",
"args": ["-y", "godotlens-mcp"]
}
}
}