Skip to main content
Glama

godot-dev-mcp

IMPORTANT

This repository is archived and no longer maintained. The project was superseded bySwallowtail, which provides the adopted Godot CLI, Editor, runtime automation, testing, and MCP workflow. This code remains available for historical reference only.

CI Version Python 3.11+ Godot 4.7.1 Mono MCP stdio License: MIT

English · 中文

Safe, composable MCP (Model Context Protocol) gateway for Godot: scene authoring, read-only runtime diagnostics, and allowlisted verification.

Current version is 0.2.0. Python 3.11+ is required.

Contents

Related MCP server: godot-ai-mcp

What it is

godot-dev-mcp lets MCP clients such as Codex inspect and change Godot projects with structured tools, instead of guessing .tscn formats or running arbitrary commands.

You can

It will not

Inspect scenes, nodes, resources, signals, and scripts

Run arbitrary shell commands

Preview a single scene-property change with dry-run

Read arbitrary files or write at runtime

Read the Editor or game scene tree, logs, screenshots, and performance

Expose the observation bridge off loopback

Run allowlisted tests and Stagehand scenarios

Bind a specific game project into the generic core

The MCP server uses standard stdio transport: one UTF-8 JSON-RPC message per line. It supports requests, notifications, and batches, and never writes non-protocol content to stdout.

Architecture

flowchart LR
  Client["MCP Client<br/>Codex / Claude"] -->|stdio JSON-RPC| Server["godot-dev-mcp<br/>Python 3.11+"]
  Server -->|"AUTHOR: inspect / dry-run patch"| Project["Godot project<br/>.tscn .gd .tres"]
  Server -->|"OBSERVE: HTTP GET loopback"| Editor["Editor Observer<br/>127.0.0.1:7331"]
  Server -->|"OBSERVE: HTTP GET loopback"| Runtime["Runtime Observer<br/>127.0.0.1:7332"]
  Server -->|"VERIFY: allowlisted argv"| Checks["project checks<br/>Stagehand adapter"]
  Addon["addons/godot_dev_mcp"] --> Editor
  Addon --> Runtime

Capability boundaries

Layer

Purpose

Write behavior

AUTHOR

Inspect scenes, nodes, resources, signals, and scripts, and patch a single scene property

Mutations default to dry-run; writes only when dry-run is explicitly disabled

OBSERVE

Read the Editor or game scene tree, node properties, performance, logs, and screenshots

Read-only; loopback HTTP GET only

VERIFY

Run allowlisted test commands and parse Stagehand, JUnit, and visual-diff output

Runs explicit argument arrays only; never through a shell

Quick start

1. Install the Python package

git clone https://github.com/DLeungDL/godot-dev-mcp.git
Set-Location godot-dev-mcp
python -m pip install -e .
python -m unittest discover -s tests -v

2. Enable the Godot addon

Copy addons/godot_dev_mcp from this repository into the target Godot project's addons/ folder. In Godot, open Project Settings → Plugins and enable godot-dev-mcp Observer.

Enabling the addon also registers the GodotDevMCPRuntimeObserver autoload. Restart the Godot Editor after the first install or an addon update so Observer loads in normal editor sessions.

3. Start the MCP server

To inspect the scene tree in the Godot Editor, use the default Editor Observer:

python -m godot_dev_mcp.server --project "C:\path\to\godot-project"

To inspect a running game, start the game from Godot first, then connect Runtime Observer:

python -m godot_dev_mcp.server `
  --project "C:\path\to\godot-project" `
  --bridge-url "http://127.0.0.1:7332"

4. Connect Codex

[mcp_servers.godot_dev]
command = "python"
args = ["-m", "godot_dev_mcp.server", "--project", "C:\\path\\to\\godot-project"]
cwd = "C:\\path\\to\\godot-dev-mcp"

To connect a running game, change args to:

args = [
  "-m", "godot_dev_mcp.server",
  "--project", "C:\\path\\to\\godot-project",
  "--bridge-url", "http://127.0.0.1:7332"
]

Observer connections

Observer

Default URL

Scope

Editor Observer

http://127.0.0.1:7331

Godot Editor scene tree

Runtime Observer

http://127.0.0.1:7332

Running game scene tree

Quick health checks:

Invoke-RestMethod http://127.0.0.1:7331/health
Invoke-RestMethod http://127.0.0.1:7332/health

Runtime Observer starts in debug builds only. To enable it in a release build, set:

godot_dev_mcp/allow_release_observer=true

Change the runtime port with godot_dev_mcp/runtime_port. If you change the port, the MCP server --bridge-url must match.

Runtime Observer uses a custom Godot Logger to capture engine messages, push_warning(), push_error(), script errors, and shader errors. Logger callbacks enqueue work under a Mutex; the main thread then writes a ring buffer of at most 500 entries. Screenshots need a display server; headless mode returns 503 Service Unavailable.

Tools

Layer

Tools

AUTHOR

godot_project_info, godot_scene_inspect, godot_scene_patch, godot_resource_inspect, godot_script_diagnostics

OBSERVE

godot_runtime_snapshot, godot_runtime_property, godot_runtime_logs, godot_runtime_screenshot, godot_runtime_errors, godot_resource_leaks

VERIFY

godot_run_check, godot_stagehand_scenario, godot_validate_scene, godot_validate_autoload

godot_scene_patch defaults dry_run to true. A write happens only when you pass false, and only for a single .tscn property. Node selectors accept a name, relative path, or full scene path; ambiguous names are rejected. Replacing an existing multiline property removes the full old value. The result includes the resolved scene_path plus a before/after change summary.

godot_scene_inspect returns bounded structured_nodes with node name, type, parent, scene path, and up to 100 properties. Multiline properties keep their full serialized form. Each value is capped at 4,096 characters, each node at 32,768 characters, and the whole scene at 131,072 characters. Truncated items are listed in truncated_properties. Pass an optional node selector to get an exact selected_node by name or scene path; use the full path when the name is not unique.

godot_runtime_snapshot returns a depth-first flat nodes page with pagination:

  • Default limit=100, maximum 500

  • Use next_offset for the next page

  • max_depth maximum is 16

  • offset maximum is 100000

Project config and VERIFY

Copy examples/godot-dev-mcp.example.json to godot-dev-mcp.json at the target project root, then edit it for that project.

{
  "checks": {
    "smoke": ["godot", "--headless", "--path", ".", "--quit-after", "60"]
  },
  "stagehand": {
    "command": ["godot-stagehand", "run", "--out-dir", "stagehand-artifacts"],
    "junit": "stagehand-artifacts/junit.xml",
    "report": "stagehand-artifacts/report.json",
    "visual_diff": "stagehand-artifacts/visual-diff.json"
  }
}
  • Check names are the allowlist accepted by godot_run_check.

  • Commands must be non-empty string arrays and start with shell=false.

  • Timeouts are 1–900 seconds.

  • Stagehand stays a separate adapter; this project only passes a scenario and parses structured artifacts.

  • A Stagehand scenario example is in examples/auction-ui.stagehand.json.

Verification status

CI in this repository runs:

  • Python unit tests and MCP stdio subprocess integration tests

  • Python compileall plus wheel/sdist packaging

  • Godot 4.7.1 Mono headless Editor addon load

Runtime Observer has also been checked against the official 2d/dodge_the_creeps demo: it can read a real game scene tree, performance monitors, and structured runtime errors.

The version 2 integration roadmap is in Issue #1.

Safety boundaries

  • Project paths are resolved and path traversal is rejected.

  • The observation bridge must use HTTP loopback.

  • Runtime properties are limited to engine properties; script-defined properties are not exposed.

  • Lists, process output, tree depth, snapshot pages, and log buffers are all bounded.

  • There is no arbitrary shell command, arbitrary file-read, or runtime write interface.

  • Project-specific extensions are off by default; the generic core does not depend on game-specific code.

License and sources

This project is MIT licensed and is a clean-room implementation. Interface review and attribution for external projects are in THIRD_PARTY_NOTICES.md.

Available Tools

15 tools
godot_project_infoC

Inspect the configured Godot project.

NameRequiredDescriptionDefault

No parameters

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. “Inspect” implies a read operation, but the description does not disclose permissions, side effects, return contents, or whether any project configuration is affected. It provides almost no behavioral context beyond the verb.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single short sentence with no wasted clauses and is front-loaded with the core action. Its brevity is appropriate structurally, though the content itself remains thin.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must explain enough for an agent to know what project information will be returned. It does not describe whether the result contains paths, settings, version data, or editor state, leaving the tool's utility ambiguous. This is insufficient for confident selection among many sibling inspection tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to explain. The baseline score of 4 applies because the description does not need to compensate for an input schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a clear verb and resource: inspecting the configured Godot project. However, “inspect” is broad and does not state what project information is returned or how this differs from sibling inspection tools such as godot_scene_inspect or godot_resource_inspect. It is understandable but vague about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no when-to-use guidance, no exclusions, and no alternatives. It does not explain whether this tool should be used before scene/resource inspection or what conditions make it appropriate. Usage must be inferred entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_resource_inspectC

Inspect a project resource without modifying it.

NameRequiredDescriptionDefault
pathYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does disclose that the operation does not modify the resource, but it says nothing about permissions, supported resource types, failure modes, or what information is returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single sentence is front-loaded and contains no wasted words. However, it is under-specified rather than appropriately concise for a tool that must be selected correctly among many siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a simple schema and no output schema, but an inspection tool should still state what it returns, what resource types it handles, and how to interpret the path. None of that is present, leaving key usage context missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one required parameter, path, and schema description coverage is 0%. The description does not explain whether the path is a res:// path, a filesystem path, or which resource types are accepted, so the parameter remains ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource pair: inspect a project resource. It also clarifies the operation is non-modifying. However, it does not distinguish this tool from nearby siblings such as godot_scene_inspect or godot_resource_leaks, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives like godot_scene_inspect, godot_project_info, or godot_resource_leaks. There are no stated preconditions, exclusions, or routing cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_resource_leaksB

Find RID, ObjectDB, and resource teardown warnings.

NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about whether the engine/editor must be live, whether it reads accumulated logs versus probing current state, or whether results are per-run. Only the word "Find" weakly implies a read-only, non-destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with the diagnostic target front-loaded and no filler. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema and no annotations, the description should at least say what comes back and what state the project must be in. It identifies the subject matter well but leaves the agent guessing about invocation context and result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description neither helps nor harms here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Find") and a concrete resource ("RID, ObjectDB, and resource teardown warnings"), which is a recognizable Godot leak-diagnostic category. It is distinguishable from godot_runtime_errors and godot_script_diagnostics by the leak/teardown framing, though it never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to reach for this tool, no preconditions (e.g. must the engine be running, must the project have just been stopped), and no pointer to a sibling that covers a nearby case. The agent must infer from the name alone that this is a post-run or teardown diagnostic.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_run_checkC

Run a command from the explicit project allowlist.

NameRequiredDescriptionDefault
nameYes
timeoutNo

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose one important behavioral trait: execution is restricted to an explicit project allowlist. However, it says nothing about what happens for non-allowlisted commands, whether execution is mutating or destructive, how output/exit status is returned, or how timeouts affect the run.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single front-loaded sentence with no filler. It is concise to the point of under-specification, but the sentence itself earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a command-execution tool with no annotations, no output schema, and no parameter descriptions, the definition is missing the behavioral and parameter detail an agent needs to call it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only loosely implies that 'name' is an allowlisted command key, and it says nothing about the 'timeout' parameter, its units, or its 1–900 range.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action and constrained resource: running a command drawn from the project's explicit allowlist. It distinguishes itself from the sibling tools, which are all inspection/validation utilities, by being the only command executor. It stops short of clarifying what 'name' identifies or who owns the allowlist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the many inspection siblings, nor on preconditions such as how the allowlist is configured. The only implied rule is that the command must already be allowlisted, which is a constraint rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_runtime_errorsB

Return warning and error entries from the observer.

NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the source ('the observer') and entry types, but does not explain whether this is a read-only snapshot, whether entries are cleared, ordering, pagination, or any other runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It is concise and structurally clear, though its brevity leaves out useful context rather than being maximally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no output schema, the description states the source and content type but not the return shape, ordering, or relationship to sibling diagnostic tools. It is minimally viable but has clear gaps for an agent deciding how to interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, a 4 is appropriate; the description does not need to compensate for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Return,' and a specific resource, 'warning and error entries from the observer.' It is clear what the tool retrieves, but it does not distinguish this tool from close siblings such as godot_runtime_logs or godot_script_diagnostics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives. A reader can infer that it retrieves runtime warnings/errors, but there is no statement about when-not to use it or which sibling to choose for similar diagnostics.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_runtime_logsC

Read the bounded observer log ring buffer.

NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Bounded' and 'ring buffer' hint that logs are limited and older entries are overwritten, but there is no information on return format, ordering, volume, or whether the read is purely observational.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. For a zero-parameter read tool, this is appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, no annotations, and no parameter documentation, the description should explain what the logs contain and how they relate to sibling tools like godot_runtime_errors. It leaves an agent unable to judge the tool's output or selection criteria.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no parameter semantics to document. The baseline score of 4 applies because the description does not need to compensate for an empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (Read) and resource (log ring buffer), but 'bounded observer log ring buffer' is jargon-heavy and does not clarify what 'observer' logs contain or how this differs from siblings like godot_runtime_errors. An agent can infer it retrieves logs, but the scope remains vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus godot_runtime_errors or godot_runtime_snapshot. The implied usage is reading logs, but no conditions, alternatives, or exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_runtime_propertyC

Read one runtime Node property from the read-only bridge.

NameRequiredDescriptionDefault
nodeYes
propertyYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does disclose the operation is read-only against a bridge, but says nothing about failure modes (node not found, property missing), whether the bridge must be attached/paused, or how values are serialized on return.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. Brevity is appropriate, though one extra clause on node addressing would have been worth the space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Two required parameters, no output schema, and no annotations mean the description needs to explain input addressing and return shape. It explains neither, leaving the agent to guess how to target a node and what it gets back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and does not. It never clarifies whether 'node' is a scene path, a runtime pointer, or an instance id, nor whether 'property' is a simple name or a nested property path.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: reading a single runtime Node property via the read-only bridge. The scope word 'one' usefully signals this is a single-value fetch rather than a snapshot (godot_runtime_snapshot exists). It does not explicitly name a sibling it is not, so it stops short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus godot_runtime_snapshot, godot_scene_inspect, or godot_runtime_logs, and no prerequisites (e.g. whether the game must be running or paused). The only implied guidance is 'read-only', which the agent must infer the boundaries of.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_runtime_screenshotA

Capture a runtime viewport PNG as base64.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses the action and output format (base64 PNG), but does not say whether the game must be running, whether the capture has side effects, or what the response structure looks like beyond the encoding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It communicates the action, target, and output encoding efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description is nearly complete: it identifies the runtime viewport capture and states that the result is base64-encoded PNG. A bit more context about runtime requirements or expected response envelope would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline for a 4 under the rubric. There are no parameter semantics to clarify, and the description does not need to compensate for missing schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Capture) and resource (runtime viewport PNG) plus the output encoding (base64). It is clear what the tool does, but it does not differentiate itself from the sibling godot_runtime_snapshot, which may be confused with this tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus alternatives such as godot_runtime_snapshot, nor are any prerequisites or exclusions mentioned. The intended usage is only implied by the name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_runtime_snapshotC

Read one bounded page of runtime nodes and selected performance monitors.

NameRequiredDescriptionDefault
limitNo
offsetNo
monitorsNo
max_depthNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Read' plus 'bounded page' weakly signals a read-only, paginated operation, but it says nothing about requiring a running/paused game, cost, whether the snapshot is a point-in-time copy, or failure behavior when no runtime session exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler — every clause carries meaning. It is terse to the point of under-specification, but that is penalized under other dimensions rather than for waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Four parameters at 0% schema coverage, no annotations, and no output schema means the description is the only guidance available, and one sentence about paging and monitors cannot convey the node-tree shape, depth behavior, or valid monitor identifiers an agent needs to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across four parameters. The description only gestures at pagination ('bounded page') and monitor selection ('selected performance monitors'); it never explains limit/offset semantics against max_depth, the allowed monitor names, the depth bound, or the default and maximum values baked into the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Read') plus resources ('runtime nodes' and 'performance monitors') and a scoping trait ('one bounded page'). This distinguishes it from edit-time siblings like godot_scene_inspect and single-value reads like godot_runtime_property, but it never names those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies a runtime-tooling context but gives no when-to-use conditions, no when-not-to-use, and no routing to alternatives (scene_inspect, runtime_property, runtime_logs). An agent must already know the tool landscape to pick this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_scene_inspectC

Inspect structured nodes, resources, scripts, and signals in a project scene.

NameRequiredDescriptionDefault
nodeNo
pathYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full disclosure burden but delivers almost none — no statement that it is read-only, whether it walks the whole node tree or only the requested node, how large a listing may be, or whether the scene must be open/valid. "Inspect" weakly implies a read, but that is the only behavioral signal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, and the object of inspection appears first. It is efficient, though its brevity reflects under-specification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Scene inspection spanning nodes, resources, scripts, and signals is a broad, potentially large-output operation, yet with no output schema, no annotations, and undocumented parameters the single sentence leaves the agent guessing about return shape and scope. Considerably more detail is required at this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needed to explain the two parameters and did not. It never clarifies that "path" is the required scene path or what "node" does (scope to a subtree? a node path?), even though that distinction changes the call substantially.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Inspect") with a named resource ("project scene") and enumerates the inspected content types: nodes, resources, scripts, and signals. This is sufficient to distinguish it from godot_scene_patch (mutation) and godot_validate_scene (validation), though it never explicitly names the contrasting siblings such as godot_resource_inspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to choose this over godot_resource_inspect or godot_project_info, and no prerequisites or exclusions are stated. A reader must infer that this summarizes a scene while its siblings inspect a resource or the whole project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_scene_patchB

Preview or apply one controlled scene property change; dry-run defaults to true.

NameRequiredDescriptionDefault
nodeYes
pathYes
valueYes
dry_runNo
propertyYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so the description carries the full load. It does disclose the most important behavioral fact: dry_run defaults to true, so the safe path is the default and an agent must opt in to mutation. However it is silent on what persistence means, whether the write is atomic/reversible, what 'controlled' enforces, and whether a running editor conflicts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence, front-loaded with the action and mode, plus the dry-run default appended where it matters most. No filler, though the brevity is partly under-specification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A five-parameter mutation tool with no annotations, no output schema, and 0% schema coverage needs far more: parameter formats, dry-run response shape, and write-confirmation semantics are all missing. The single sentence is nowhere near sufficient for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and all five parameters are bare typed fields with no docs. The description explains only dry_run (its default), leaving path, node, property, and value — including expected formats such as a NodePath expression or property string — completely undefined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb pair (preview/apply) acting on a specific resource (a scene property change), with the scope qualifier 'one controlled' signalling a single-atom mutation. It doesn't explicitly contrast with the inspect/validate siblings, but the write-vs-read distinction is inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The mention of preview vs apply implies the two usage modes, but there is no explicit 'use this when...' guidance, no prerequisites (e.g. scene must exist / be closed), and no pointer to godot_scene_inspect or godot_validate_scene as the read-only alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_script_diagnosticsC

Return bounded static diagnostics for a GDScript or C# file.

NameRequiredDescriptionDefault
pathYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. 'Bounded' implies a result cap but the limit and truncation behavior are unexplained, and it doesn't confirm the operation is read-only or describe what diagnostics contain. A static analyzer is presumably safe, but the agent must infer that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is efficient, though it is terse to the point of omitting useful detail rather than trimming waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a diagnostics tool with no output schema and no annotations, the description never indicates what the returned diagnostics look like (severity levels, line numbers, counts) or how 'bounded' manifests. An agent calling it cannot anticipate the response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the sole `path` parameter is undocumented in the schema. The description partially compensates by implying path refers to a GDScript or C# source file, constraining the expected file type, but gives no format, relative-vs-absolute, or resolution guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return bounded static diagnostics') and names the input domain (GDScript or C# file), which distinguishes it from runtime-oriented siblings like godot_runtime_errors and godot_runtime_logs. It stops short of explicitly naming those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is given. The word 'static' hints that this differs from runtime error tools, but the description never states that alternative or the conditions that select it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_stagehand_scenarioC

Run a configured Stagehand scenario and parse JUnit/visual diff outputs.

NameRequiredDescriptionDefault
timeoutNo
scenarioYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so the description carries the full burden. It hints at execution plus output parsing, but says nothing about side effects on the project, whether the run is isolated, how long it may take, or what the parsed results look like. Only a partial behavioral picture.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler, but the brevity here borders on under-specification for a tool that runs scenarios and diffs output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A no-annotation, no-output-schema execution tool with fully undocumented parameters needs substantially more explanation than this single sentence provides. An agent lacks enough to call it confidently or interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description doesn't compensate: it never clarifies whether 'scenario' is a name, path, or identifier, nor does it mention the 'timeout' parameter (bounds 1-900s) at all. Both parameters remain semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Run') and resource ('configured Stagehand scenario') plus the post-processing ('parse JUnit/visual diff outputs'). It is clearly distinguishable from the inspect/validate siblings, though 'Stagehand' is unexplained jargon that leaves the domain slightly opaque.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No indication of when to use this versus siblings like godot_run_check, what a 'configured' scenario means, or any prerequisites. The agent must infer the selection context entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_validate_autoloadB

Validate project autoload paths.

NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does not state whether validation is read-only, what conditions are checked, what happens on failure, or whether any project state is modified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It is concise, though its brevity contributes to gaps in usage and behavioral context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description should explain what validation checks and what kind of result the agent receives. It does neither, leaving an agent unable to know what a successful or failed validation means.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so parameter semantics are inherently simple. The baseline for a no-parameter tool is 4, and there is no schema complexity to explain beyond the empty input object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Validate project autoload paths.' An agent can infer it checks autoload path configuration, but it does not explicitly distinguish this from the sibling godot_validate_scene.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, when not to use it, or how it relates to alternatives such as godot_validate_scene. Usage is only implied by the word 'Validate.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_validate_sceneC

Validate a project scene.

NameRequiredDescriptionDefault
pathYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not say whether validation is read-only, what kinds of problems it detects (syntax, missing dependencies, broken references), or what happens on invalid input. Only the word 'validate' implies non-mutating behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence with no filler, which is appropriately terse. However, the brevity reflects under-specification rather than disciplined editing, so it earns only a middling score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no annotations, so the description should explain what a validation result contains (errors, warnings, success indicator). Combined with the undocumented path parameter, an agent cannot confidently predict the call's behavior or response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single required parameter 'path' has 0% schema description coverage, so the description must explain it but does not. It never clarifies whether the path is a filesystem path or a res:// project path, or whether directories are accepted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Validate a project scene" gives a specific verb and resource, so the general intent is clear. But it never distinguishes itself from siblings like godot_scene_inspect or godot_run_check, leaving the agent unsure what 'validate' covers versus inspecting or running a check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus godot_scene_inspect, godot_run_check, or godot_script_diagnostics, and no prerequisites or failure conditions are mentioned. The agent must infer usage purely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 15 tool updatesv0.2.0
    • First observedgodot_project_info
    • First observedgodot_resource_inspect
    • First observedgodot_resource_leaks
    • First observedgodot_run_check
    • First observedgodot_runtime_errors
    • First observedgodot_runtime_logs
    • First observedgodot_runtime_property
    • First observedgodot_runtime_screenshot
    • First observedgodot_runtime_snapshot
    • First observedgodot_scene_inspect
    • First observedgodot_scene_patch
    • First observedgodot_script_diagnostics
    • First observedgodot_stagehand_scenario
    • First observedgodot_validate_autoload
    • First observedgodot_validate_scene

TDQS

B3.2/5.0

Scored across 15 tools

Disambiguation4/5

Most tools target clearly distinct scopes: project info, scene/resource inspection, runtime reads, diagnostics, validation, and controlled patching. There is some overlap among runtime diagnostics tools (logs, errors, leaks) and between scene inspection and scene validation, but the descriptions provide enough distinction for selection.

Naming Consistency4/5

All names use snake_case and a consistent godot_ domain prefix, making them easy to scan. Most follow a scope_action or scope_noun pattern, though a few variants like godot_run_check and godot_stagehand_scenario are slightly less predictable.

Tool Count5/5

Fifteen tools is well-scoped for a Godot project inspection, validation, and runtime debugging server. Each tool appears to cover a distinct operational area without obvious padding.

Completeness4/5

The surface covers project inspection, scene/resource inspection, validation, runtime observation, diagnostics, screenshots, allowlisted execution, and scenario testing. Minor gaps exist around broader scene/resource editing or creation, since scene_patch only previews/applies one controlled property change.

Maintenance

ActivitySlowing
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    C
    quality
    C
    maintenance
    Enables AI-driven game development by providing MCP tools to interact with the Godot editor, including scene editing, node manipulation, script attachment, and scene execution.
    28
    8 npm
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Provides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.
    21
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides progressive-disclosure MCP access to Godot editor development, enabling tool discovery, task execution, inspection, and status tracking for projects across Godot 4.5 to 4.8-dev.
    MIT
  • A
    license
    C
    quality
    C
    maintenance
    Enables MCP clients to inspect, validate, test, export, and query Godot projects, including live state from an open editor via a bridge addon.
    20
    17 npm
    MIT