Drives a Unity project's build, test, and screenshot loop from an MCP client in batchmode, providing tools for compiling, testing, building, and capturing screenshots of Unity projects.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@headless-unity-mcp compile the project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
drive a unity project's build/test/screenshot loop from an MCP client — in batchmode, with no interactive editor open, ever.
six tools: unity_compile, unity_test, unity_scene, unity_build, unity_shot,
unity_targets, plus unity_status. each returns a compact structured verdict, not a wall
of unity log:
{"ok": true, "verdict": "OK EditMode total=234 passed=234 failed=0",
"totals": [{"platform": "EditMode", "total": 234, "passed": 234, "failed": 0,
"results_xml": "/path/Logs/editmode-results.xml"}]}macOS only, for now. see limitations.
if you point an agent at a unity project, three things go wrong.
unity's exit codes lie. the editor exits 0 with error CS0103 sitting in the log. it
exits nonzero when everything compiled. it writes no test results XML at all and still
exits 0. an agent that trusts $? will tell you the build is green when it isn't, and
that's the single worst failure an agent can have — not being wrong, but being confidently
wrong.
batchmode output is a context bomb. a single -batchmode compile emits tens of
thousands of lines even with -logFile set. a player screenshot is a PNG that costs
thousands of tokens to look at. dump either into an agent's context and you've spent the
budget you needed for the actual work. the usual workaround — wrap every call in a
throwaway subagent that summarizes — is real overhead you shouldn't have to pay.
the existing unity MCP servers need a live editor. near all of them (coplaydev, codergamester, ivanmurzak, anklebreaker, unity's own first-party package) are editor-embedded bridges: a C# package that opens a socket inside a running, interactive unity editor. that's the architecture, not a gap in the docs. it means you cannot run headless, you cannot run in CI, and you inherit the domain-reload problem — recompile your scripts and the bridge's C# state is torn down underneath it, so the agent goes deaf mid-task (coplaydev #814 — "agents sleep after script changes").
Related MCP server: mcp-server-unity
spawn-and-exit. every verb launches Unity -batchmode -nographics, waits for it to exit,
and parses the evidence it left on disk. there's no long-lived editor to go stale, so the
domain-reload bug class doesn't exist here — the process is gone before the next call
starts.
the verdict is derived from evidence, never from the exit code:
what | the actual verdict |
compile | a |
test | the NUnit results XML. missing XML is a FAIL, and any |
build | the |
shot | a PNG over 10KB captured from the player's real window, by |
fatal abort |
|
editor-embedded bridges | headless-unity-mcp | |
needs an interactive editor open | yes | no |
survives a script recompile mid-task | no (domain reload tears down the bridge) | n/a — nothing is long-lived |
usable in CI / over ssh / on a headless box | no | yes |
"run tests" means | the live test-runner API |
|
trusts unity's exit code | typically yes | never |
screenshots | the editor window (or unsupported on macOS) | the built player's window |
concurrent calls | undefined | machine-wide lock, one cycle at a time |
project-specific setup | a C# package in your project | one toml file |
the honest counterpoint: an embedded bridge can do things a batchmode process fundamentally
can't — inspect a live scene graph, read the editor console in real time, poke a
GameObject while the game is running, offer 40+ fine-grained tools. if that's what you
need, use one of those. this server does five verbs and does them verifiably.
macOS. the screenshot path is Quartz + screencapture, and the build targets a mac
standalone player. the compile/test/build verbs are portable in principle; nothing else
has been ported yet.
unity — any version, installed via the hub (or point [unity] path anywhere).
python 3.11+ (needs tomllib).
for unity_shot: pyobjc-framework-Quartz, plus the Screen Recording grant for
whichever app hosts your shell. macOS gates all window capture behind it; without the
grant every capture fails with could not create image from window. the driver preflights
this and refuses with the fix rather than writing you a black PNG.
git clone https://github.com/Shonas301/headless-unity-mcp
cd headless-unity-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[shot]" # drop [shot] if you don't need screenshotsdrop a unity-mcp.toml in the root of your unity project (next to Assets/ and
ProjectSettings/). this is the only project-specific file — the server and the driver stay
generic.
default_target = "mac"
[unity]
version = "6000.5.0f1" # validated against ProjectSettings/ProjectVersion.txt
# path = "/Applications/Unity/Hub/Editor/6000.5.0f1/Unity.app/Contents/MacOS/Unity"
[shot]
delay_s = 9 # wait out the unity splash; the splash window is NOT the game window
width = 800
height = 600
[targets.mac]
build_method = "MyGame.Editor.BuildScript.BuildMacDev" # a public static method, via -executeMethod
app_path = "Build/Mac/MyGame.app"
# optional — only if your project authors scenes from code
scene_method = "MyGame.Editor.SceneBuilder.Generate"
scene_path = "Assets/Scenes/Main.unity"build_method is an ordinary editor static method, the same one you'd call from CI:
public static class BuildScript {
public static void BuildMacDev() { BuildPipeline.BuildPlayer(/* ... */); }
}that [unity] version check is load-bearing. it's what stops a call aimed at the wrong
project from cheerfully reporting all-green — a real failure mode, and one that is very hard
to notice, because every individual line of the output looks fine.
see unity-mcp.example.toml for the annotated version.
.mcp.json (claude code, and most clients take the same shape):
{
"mcpServers": {
"unity": {
"command": "/abs/path/to/headless-unity-mcp/.venv/bin/python",
"args": ["-m", "unity_mcp.server"],
"timeout": 1800000
}
}
}the long timeout matters: a build or a PlayMode run takes minutes, and a queued call
blocks until the machine lock frees. progress notifications do not extend an MCP
client's tool timeout, so the timeout has to actually cover the wait.
every tool takes an optional workspace (absolute path to the unity project). omit it and
the server uses its own cwd, which is what you want when the client launches one server per
project.
tool | what it does |
| import + compile all assemblies. verdict is a log grep, never |
|
|
| regenerate a target's scene via its |
| build a target's standalone player via its |
| launch the built player, screenshot its window, return the PNG path. |
| list the targets this project defines. never takes the lock. |
| who holds the machine lock right now. never takes the lock. |
there is one unity binary and one license on your machine, and two editors cannot open the
same project at all — the second one dies with Multiple Unity instances cannot open the same project. so the server serializes.
it has to be a real OS lock, not an in-process one: each MCP client spawns its own stdio
server process, so an asyncio.Lock would serialize nothing across them. this uses
fcntl.flock on a file under ~/.cache/headless-unity-mcp/, machine-wide. a second caller
blocks until the first finishes (bounded by queue_wait_timeout_s, default 900s), then
runs. if it gives up, the refusal names who held the lock and since when.
unity_status reads the holder without taking the lock, so you can always ask.
unity_shotit returns the PNG's path, not the image. that's deliberate, but it means the one context bomb this server can't defuse is still live: deciding whether a screenshot shows a real gameplay frame or the unity splash requires looking at pixels, and that's thousands of tokens whoever does it.
so: read the PNG in a throwaway subagent, not in your main context. ask it for one sentence. the other five verbs return one-line verdicts and need no such thing.
the driver is a plain shell script and works with no MCP client at all:
UNITY_MCP_PROJECT=/path/to/project ./src/unity_mcp/driver.sh compile
UNITY_MCP_PROJECT=/path/to/project ./src/unity_mcp/driver.sh test edit
UNITY_MCP_PROJECT=/path/to/project ./src/unity_mcp/driver.sh build macit prints the same verdict lines the tools parse, and exits nonzero on failure. the MCP server shells out to exactly this file — a verdict you see through a tool is a verdict this script printed. there is no second implementation to drift.
the unit suite is hermetic (a stub driver fakes unity's failure modes; no unity needed):
.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check .
.venv/bin/python -m mypythe gates are the real harness — they assert the properties that actually matter, and
they write machine-readable evidence to gates/evidence/:
.venv/bin/python gates/run_gates.py # G0–G4, hermetic
UNITY_MCP_GATE_WORKSPACE=/path/to/project \
UNITY_MCP_GATE_EDIT_FLOOR=230 \
.venv/bin/python gates/run_gates.py # + G5/G6 against real unitygate | asserts |
G0 | ruff + mypy + unit suite clean |
G1 | two concurrent calls to one server don't overlap |
G2 | two concurrent calls to separate server processes don't overlap (the test an |
G3 | two workspaces, two processes, neutral cwd — each reports its own numbers (arithmetic tripwire: A must say 7, B must say 13) |
G4 | guard parity: exit-code-lies, fatal abort, missing XML, bad project and bad target both refused before the lock, and a timeout kills the whole process group (no orphaned 2GB editor) |
G5 | real unity: compile + EditMode against a real project, with a totals floor |
G6 | real screenshot: a >10KB PNG off the built player |
SKIPPED always carries a reason and is never counted as a pass.
macOS only. the shot path is Quartz-specific and the build targets a mac player.
no live-editor introspection. no scene graph, no live console, no poking a running game. that's the trade for not needing an editor.
you cannot inject input into the player. a screenshot shows you a frame; it can't
press a key. drive gameplay from PlayMode tests instead — give your controller an input
seam (a Func<Vector2> the test can set) and assert on real physics.
one project at a time per machine, by construction. that's the lock, and it's a feature.
MIT.
Build the standalone player for a target, via its configured build_method.
Call unity_targets to list target names.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| workspace | No | ||
| queue_wait_timeout_s | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the build action and the configured build_method, but doesn't disclose whether the build is long-running, whether it blocks, what side effects occur, or whether special permissions are needed. The 'queue_wait_timeout_s' parameter hints at queueing but the description doesn't explain this behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the primary function, and the second gives a practical pointer. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists, the description doesn't cover the workspace parameter or the timeout semantics, leaving gaps for a build tool. It does provide the essential build target and lists a prerequisite, but for the tool's complexity (3 params) and no annotations, more context would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 indirectly explains the 'target' parameter by pointing to unity_targets, but it doesn't clarify the 'workspace' parameter or the 'queue_wait_timeout_s' parameter. The timeout's meaning is only inferable from its name, and workspace is completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Build the standalone player') and the resource ('for a target'), with the mechanism 'via its configured build_method'. It distinguishes from unity_compile by specifying a 'standalone player' artifact, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for building a target and advises calling unity_targets to list names, which is a helpful prerequisite. However, it doesn't provide explicit when-to-use vs alternatives like unity_compile, nor any exclusions or context on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import and compile all assemblies. The verdict is a error CS grep of the unity
log, never the exit code — unity exits 0 on compile errors.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No | ||
| queue_wait_timeout_s | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and reveals a critical non-obvious behavior: success is determined by grepping the unity log for 'error CS', not the exit code, since Unity exits 0 on compile errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each adding essential information: the first states the function, the second clarifies a crucial behavior. No unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core purpose and a key behavior are covered, the description lacks parameter semantics and usage alternatives. Given no annotations and an output schema, it is only partially complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'workspace' or 'queue_wait_timeout_s' parameters. The parameter names hint at their meaning but the description adds no semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Import and compile all assemblies') with a specific verb and resource, distinguishing it from sibling tools like unity_build and unity_test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for compilation but provides no explicit when-to-use guidance or alternatives. The verdict clarification is more behavioral than usage-focused.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Re)generate a target's scene by invoking its configured scene_method. Only for
projects that author scenes from code. Call unity_targets to list target names.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| workspace | No | ||
| queue_wait_timeout_s | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, but it only mentions the action and a method. It does not disclose potential side effects (e.g., overwriting an existing scene), whether the operation blocks or queues (despite a queue_wait_timeout_s parameter), or any error/return behavior. The word '(Re)generate' hints at possible overwriting, but this is left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of three short sentences that front-load the core purpose and then provide usage context. No wasted words; every sentence contributes actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and the main prerequisite, but it is incomplete regarding parameter roles and behavioral details like queueing and potential overwrites. The presence of an output schema reduces the need to document return values, yet the description still leaves gaps for a three-parameter tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter meanings. It partially explains `target` by referring to a 'target's scene' and pointing to unity_targets for listing names, but it provides no context for `workspace` or `queue_wait_timeout_s`. The description adds minimal value beyond the schema's property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: '(Re)generate a target's scene' with a specific mechanism ('invoking its configured scene_method'). It distinguishes itself from sibling tools like unity_build, unity_test, and unity_shot by focusing on scene generation from code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Only for projects that author scenes from code' and provides a direct instruction for a necessary preliminary step: 'Call unity_targets to list target names.' This gives clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch the built player and screenshot its window by CGWindowID. Needs an existing build, the macOS Screen Recording grant, and an unlocked screen. Returns the PNG's path — read it in a throwaway subagent, not your main context.
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | ||
| workspace | No | ||
| queue_wait_timeout_s | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers prerequisites (build, screen recording, unlocked screen), the return type (PNG path), and a usage caveat (read in a throwaway subagent). It does not mention side effects like process spawning or cleanup, but the disclosed information is substantial and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and fully front-loaded: it states purpose first, then prerequisites and return behavior. Every clause earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 undocumented parameters and no annotations. While the output schema exists and the description mentions the PNG path, the lack of parameter semantics leaves a significant gap in the context needed to invoke the tool correctly. The agent would not know what target or workspace mean, especially given the sibling unity_targets and unity_build tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters (target, workspace, queue_wait_timeout_s). It does not mention any of these parameters or map them to concepts like the build target or workspace path. The agent is left without any guidance on how to fill in the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Launch the built player and screenshot its window by CGWindowID.' This identifies the resource (built player's window) and the operation (screenshot), and it inherently distinguishes from sibling tools like unity_build or unity_status, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear prerequisites: 'Needs an existing build, the macOS Screen Recording grant, and an unlocked screen.' This tells the agent when the tool can be invoked (after a build, with permissions). It does not explicitly mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who, if anyone, holds the machine lock right now. Never takes the lock.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the key behavioral trait (never acquires the lock), which is essential for safe usage. It doesn't mention error conditions or output format, but since an output schema exists, that information is available elsewhere.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose, then a key qualifier. Every word earns its place; there is zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter status tool with an output schema, the description is complete. It explains what the tool does and explicitly states a critical non-behavior. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the parameter-semantics burden is minimal. The description adds no parameter details, but none are needed. The baseline for 0-param tools is 4, and no gaps are present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it reports who holds the machine lock. It also adds a critical qualifier ('Never takes the lock') that distinguishes it from actions that might acquire the lock. This is a specific, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need to check lock status without acquiring the lock. It explicitly says 'Never takes the lock,' which serves as a safety guideline. It doesn't explicitly name alternatives, but among sibling tools it's clearly the only status-checking tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the build targets this project defines in unity-mcp.toml. Never takes the lock.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It clearly states the read-only nature ('List') and the lock-free guarantee, which are important for an agent to assess side effects. It does not describe error cases or file-location details, but the core behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It front-loads the action and resource, then adds the key lock-free constraint without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the output schema likely explains return values. However, the complete absence of parameter guidance and the lack of explicit usage alternatives make the description less complete than ideal. The lock-free note adds valuable context, but the parameter gap prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter ('workspace') with zero description coverage, and the description never mentions it. The agent receives no guidance on what the parameter controls (e.g., which project's targets to list) or how the default empty string behaves, leaving a critical semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List'), the resource ('build targets'), and the source ('unity-mcp.toml'). It distinguishes itself from siblings like unity_build or unity_compile by being a listing operation, and the lock-free note adds a unique scoping constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inspecting available build targets, and the explicit 'Never takes the lock' provides practical guidance that it is safe to call concurrently with builds. However, it does not explicitly mention when not to use it or compare with alternatives, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run EditMode and/or PlayMode tests. The results XML is the evidence: a missing XML is a FAIL, any result="Failed" is a FAIL. Returns parsed per-platform totals.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | all | |
| workspace | No | ||
| queue_wait_timeout_s | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It goes beyond a simple 'runs tests' by explaining the exact failure criteria: a missing XML is a FAIL, and any result="Failed" is a FAIL. It also states that it returns parsed per-platform totals, giving the agent insight into what to expect from the tool's output and how to interpret results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding distinct value: the action, the failure evidence semantics, and the return type. There is no repetition of schema information or fluff. It is perfectly front-loaded with the primary action and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for a test-running tool: it covers the operation, critical behavioral details (XML-based failure detection), and return summary. The main gap is the lack of context for 'workspace' and 'queue_wait_timeout_s,' but these are auxiliary parameters with defaults. The presence of an output schema also reduces the need to explain return structure in the description. Overall, it is adequate and informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 for parameter meaning. It does clarify 'platform' by tying it to EditMode/PlayMode tests, but it gives no explanation for 'workspace' or 'queue_wait_timeout_s.' The schema only provides names and defaults, leaving the agent to guess the purpose of these parameters. Thus, compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Run EditMode and/or PlayMode tests.' This clearly identifies the tool's function and distinguishes it from sibling tools like unity_build or unity_compile, which handle other Unity CI tasks. No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description does not explicitly name alternative tools or state 'when not to use,' it provides clear context by specifying the test modes (EditMode/PlayMode) and the per-platform totals. This implicitly signals when the tool is appropriate—whenever Unity tests need to run—but lacks explicit exclusions or comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0unity_buildunity_compileunity_sceneunity_shotunity_statusunity_targetsunity_testEach tool maps to a distinct Unity operation: screenshot, lock status, build, list targets, compile, test, and scene generation. Build vs compile are clearly differentiated by their descriptions, and no two tools appear to serve the same purpose.
All tools share a consistent 'unity_' prefix, but the action words mix verbs (build, compile, test) with nouns (shot, status, targets, scene). This is mostly predictable but deviates from a pure verb_noun pattern.
With 7 tools, the server is well-scoped for a Unity CI/headless workflow. Each tool covers a specific need without redundancy, and the count is well within the ideal 3-15 range.
The tool surface covers the core lifecycle: build, compile, test, screenshot, and scene generation, plus target listing and lock status. Minor gaps like explicit lock release or raw log retrieval are workarounds, but the main workflows are complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Run commands on your computers remotely with TRIGGERcmd.
Automate cloud Chrome—navigate, click, type, screenshot, run code, record screen video
Drive a live Cinevva game session: edit game files, import CC0 assets, preview changes.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Shonas301/headless-unity-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
