Ghost Inspector MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Ghost Inspector MCP listing page.
ghost-inspector-mcp
An MCP server for the Ghost Inspector API, so you can work with end-to-end browser tests from whatever agent you already use — Claude, OpenAI, OpenCode, your own automation — instead of clicking through the web UI.
Status
Fourteen tools. Nine only read, four write, and one runs a test for real. All of them are always listed — the gated ones refuse when called without their opt-in rather than hiding, so nothing has to be inferred from an absent tool.
The table is a map of the surface. Each tool's own description, which is what your agent actually reads, is where the detail and the gotchas live.
Understand an account
| Tool | Access | What it does |
|---|---|---|
gi_whoami | read | Verifies your API key, lists the organizations it can reach with their ids, and reports which gates are open. Start here when something is misconfigured, or when an agent tells you this server cannot modify anything. |
gi_inventory | read | The whole account as a folder → suite tree, with per-suite counts of passing / failing / module / not-yet-run tests and the names of the failing ones. Filter by folder, or ask for failing suites only. |
gi_module_usage | read | The reverse index of execute steps: for every imported test, who imports it directly and its full transitive blast radius. Also finds modules nobody imports, imported tests missing the import-only flag, broken references, and cycles. One request per test. |
gi_get_test | read | One test's stored definition, identity and state — including the dateUpdated that gi_update_test requires as its concurrency token. Call it before composing any edit. |
Find what is wrong
| Tool | Access | What it does |
|---|---|---|
gi_stale_tests | read | Splits red tests into stale and genuinely broken by comparing the whole execute chain's dateUpdated against each test's last run. Also finds passing tests whose result predates a change. One request per test. |
gi_vacuous_tests | read | Green tests that prove nothing, in three separate classes: runs zero steps; runs its steps but contains no assertion at all; or a shortlist whose lone final assertion may have been true before the test did anything. |
gi_test_result | read | Why one test is red: the failing step, its error, the selectors it was authored with rather than only the one that resolved, and which test or module actually owns the step. Leads with a staleness verdict, because a result that predates a change is not evidence. |
Fix it
| Tool | Access | What it does |
|---|---|---|
gi_propose_repair | read | Turns a diagnosis into a concrete proposal: the rewritten step, which test owns it, and the token to write it. Applies nothing, and refuses on a stale diagnosis. |
gi_validate_test | read¹ | Runs a definition through on-demand execution, which executes and discards it, and reports every step. Inlines modules first, then truncates at the first step that could submit a form. dryRun shows what would run without starting a browser. |
gi_update_test | write | Replaces a test's steps and/or renames it, behind four guards and a concurrency token. |
gi_move_suite | write | Moves a suite with its tests to another folder. Reversible; returns the prior folder so the undo is one call. |
gi_create_suite | write | Creates an empty suite, in a folder if you name one. Refuses a same-named sibling unless you insist. |
gi_duplicate_test | write | Copies a test, places it in a suite and renames it in one call. The only way to get a new test — Ghost Inspector has no create endpoint — so a source test is required. Clears the copy's schedule by default. |
gi_run_test | run | Executes a test exactly as saved and waits for the verdict. Its own gate, separate from writes. A test that submits a form is refused unless you confirm on that call. |
¹ gi_validate_test saves nothing, but it drives a real browser against a real URL, so it is not marked read-only.
The four write tools refuse unless GHOST_INSPECTOR_ALLOW_WRITES is exactly true, and gi_run_test refuses unless GHOST_INSPECTOR_ALLOW_RUNS is. A refusal changes nothing and names the variable to set. gi_whoami reports both gates.
Not included, on purpose. Deletion of any kind. DELETE /suites/{id}/ cascades to every test in the suite with no undo, and that blast radius does not belong behind an agent; deleting a test is left out for the same reason, since there is no version history to restore from.
Creating a test from nothing is not possible. Ghost Inspector exposes no create endpoint — POST /tests/ returns the test listing, the organization- and folder-scoped variants return 404, and the vendor documents update, duplicate and delete with no create. gi_duplicate_test is the supported route: copy an existing test, place it, rename it. It is named for what it does, because calling it "create" would set the wrong expectation about needing a source.
Not built. Dating a regression back to its last green run. Old results are purged, so there is a horizon past which the API cannot answer it, and a tool that silently stops working at an unknown depth is worse than no tool.
What you can ask for
You talk to your agent, not to the tools. These are the questions the server is built to answer:
- "Which of my failing tests are actually broken, and which just haven't run since someone edited them?" — the distinction the dashboard cannot make, and the reason a triage session usually starts here.
- "Why is the checkout test red?" — the failing step, its error, and which test or module owns it.
- "If I change this shared module, what breaks?" — direct importers and the full transitive reach, which is normally much larger.
- "Which of my green tests aren't really testing anything?" — three separate ways a test can pass while proving nothing.
- "Fix that selector." — propose a change, run it without saving to check it resolves, apply it behind the guards, then run the test to confirm. Each step is a separate tool, and the ones that change or execute anything need you to opt in first.
A note on scale. This server earns its place on accounts that have accumulated mess: hundreds of tests, shared modules with unclear ownership, a failing list nobody has triaged in months. On a small, well-tended account — a couple of dozen tests, no modules, everything green — gi_stale_tests, gi_module_usage and gi_vacuous_tests will correctly return nothing, and the server will look like it does very little. That is the honest answer for that account, not a malfunction.
Why this exists
Ghost Inspector's API is small and stable, so a 1:1 wrapper would add nothing over curl. This server is for the three things curl cannot give you:
- Aggregations the API does not provide — the account as a folder → suite tree with honest counts, the reverse index of which tests import each module, and red tests split into genuinely broken versus merely out of date.
- Guardrails on the write path — there is no version history for test steps and no recycle bin. Overwrites are forever.
- Tool descriptions that teach the calling model how not to break things — the accumulated gotchas ship with the tool, so every agent gets them for free instead of learning them the expensive way.
Other community wrappers of this API exist. The difference here is the posture: nothing is written or executed until you opt in, no deletion at any opt-in level, and every write behind guards that cannot be turned off.
Two worked examples of that third point, because it is the whole thesis.
Marking a test Import Only — Ghost Inspector's way of saying "this is a module, other tests import its steps" — deletes its stored results. Every module is therefore permanently "never executed": no results, passing not a boolean, last-run date pinned to the 1970-01-01 epoch sentinel. The obvious implementation of stale-test detection sorts by last-run date, so it reports every module in your account as the deadest, most broken thing in it, and advises deleting exactly the steps all your live tests share. This server knows that, and ships the predicate that prevents it.
And a test whose steps are only execute calls into modules with no steps runs zero steps and passes, because nothing can fail. The dashboard shows it green while it asserts nothing, which is worse than red because nobody investigates green. Emptying one shared module does that to every test importing it, silently and all at once.
That is the smallest of three ways a test can be hollow. On a real account of a few hundred tests, gi_vacuous_tests found that the largest group by far was not this one but tests that run every step and contain no assertion at all — they can only fail if a step errors. A third group asserts only on its final step, which may well have been true before the test did anything. All of them green.
Install
Requires Node 18+. There is nothing to install ahead of time — your MCP client launches the server with:
Those two prompt for your key and store it in VS Code's own secret input rather than in a settings file.
To work on the server itself, clone and build instead:
Configure
Get your personal API key: Ghost Inspector → hover your name (top right) → Account Settings → API Access. Keys are per user, and regenerating one disables the previous key immediately.
| Variable | Required | Purpose |
|---|---|---|
GHOST_INSPECTOR_API_KEY | yes | Your personal key |
GHOST_INSPECTOR_ORG_ID | to execute a validation | Organization id — read it from gi_whoami. Not needed for gi_validate_test's dryRun |
GHOST_INSPECTOR_ALLOW_WRITES | no (default false) | Set to true to let the four mutating tools act. They are listed either way |
GHOST_INSPECTOR_ALLOW_RUNS | no (default false) | Set to true to let gi_run_test execute. Not implied by ALLOW_WRITES — an edit can be rolled back from the backup this server returns, a submitted form cannot |
Configuration is environment variables only. There is deliberately no .env support: this ships as a global command with no project directory of its own, and a second place to put a secret is a second place to leak it. The key is read fresh on every call, so rotating it takes effect without a restart.
Claude Code
Claude Desktop, Cursor, Windsurf and anything else that takes a JSON config
No env block: the server inherits the environment of whatever launched your client, so exporting the key in your shell profile is enough and it never has to sit in a config file. Add one only if your client cannot inherit it.
Any other MCP client
Point it at npx -y ghost-inspector-mcp over stdio, or at node <path>/dist/index.js from a clone, and pass the key through the environment.
If the tools appear but every call says the key is missing
Your client was almost certainly launched from a desktop icon, Spotlight or a launcher rather than a terminal. Those do not run a login shell, so ~/.zprofile and ~/.bash_profile are never read and your export never happened — the server starts fine and registers its tools, then finds nothing in the environment.
Either launch the client from a terminal, or have the server read the key itself at launch:
The same wrapper works as "command": "sh" with "args": ["-c", "..."] in a JSON config. The key stays in a 600 file that only your user can read, and never enters the client's configuration.
Handling your API key
Ghost Inspector authenticates with ?apiKey= in the query string, so the credential ends up in shell history, proxy logs and AI conversation transcripts unless you are deliberate about it.
printf rather than echo matters: a trailing newline corrupts the key inside a query parameter.
This server will never:
- ask for your key through a tool call (that would put your secret in a conversation transcript)
- write your key to disk
- include your key in a log line, an error message or a tool response
Safety model
Nothing is written or executed unless you opt in. The mutating tools act only when GHOST_INSPECTOR_ALLOW_WRITES=true, and gi_run_test only when GHOST_INSPECTOR_ALLOW_RUNS=true. Without those, nothing can be changed or run no matter what your agent is asked to do — the check is in the handler, so it holds regardless of what the caller sends. Every tool also declares MCP annotations (readOnlyHint, destructiveHint), so a client that gates permissions on them sees the same posture the server enforces — including that gi_validate_test is not marked read-only, because driving a real browser against a real URL is a side effect even when nothing is saved.
Gated, never hidden. Every tool is listed whether or not its gate is open, and the permission check runs when the tool is called. A tool that is withheld from the listing is indistinguishable from one that does not exist, so an agent reading a short list concludes the capability is missing and tells you so — with nothing available to correct it. Here a gated call refuses, touches nothing, and names the variable to set.
Visibility is not permission. The two are separate on purpose: the listing tells the agent what this server can do, the gate decides what it may do right now.
Suite deletion is not exposed, by design. DELETE /suites/{id}/ cascades to every test in the suite, with no version history and no recycle bin. That stays a deliberate curl by someone who knows what they are doing.
Failed requests are not retried. A timeout or a dropped connection surfaces as an error instead of being attempted again. That is a decision, not an omission: execute and the write endpoints are not idempotent, and a retry that silently ran a browser test twice — or re-applied a write whose first attempt actually landed — buys convenience with exactly the kind of surprise this server exists to prevent. Read-only calls are safe to retry, so your agent can simply ask again.
Writes are guarded. Every mutating tool performs these four in order, and none can be turned off:
- compare
dateUpdatedacross the wholeexecutechain against the last run — a red test whose module was edited after its last run is stale, not broken, and a fix diagnosed from that failure is diagnosed from a version that no longer exists. Imports nest up to ten levels, so the walk is bounded and detects cycles. On a real account this refused a test that had been red on the dashboard for well over a year, whose definition had been edited weeks after that last run; - return the complete prior definition — on refusals too. Ghost Inspector keeps no version history of steps, so that object is your rollback;
- apply the change;
- re-read and diff twice over: that what was sent landed exactly, and that every field you did not send is untouched.
HTTP 200proves neither.
Writing also requires a concurrency token. You state the dateUpdated you believe is current, and the write is refused if the record has moved since. A confirmation flag can be talked past by a persuaded model; a timestamp it has to have actually read cannot be guessed. gi_get_test returns that token alongside the definition, so reading the record is the ordinary first step of an edit rather than an obstacle.
A refusal reports the current value, because that is part of diagnosing a genuine conflict, and directs you to re-read and rebuild the change rather than resend it. Replaying an edit composed against a definition that is no longer stored would overwrite whatever replaced it.
That token narrows the window rather than closing it. Ghost Inspector has no compare-and-swap, so the check is read-then-write on the client side: two writers who both read before either wrote will both pass. It catches acting on a copy you read minutes or days ago, which is the realistic case, not a genuine race.
All four guards are verified against a live account, on a disposable clone that was created, written to and deleted, leaving the account byte-identical afterwards. One behaviour that only surfaces there: Ghost Inspector normalises steps on write, filling in fields the caller omitted, so both sides are normalised before being compared. Without that, verification reports a difference on every write that landed perfectly.
Running a stored test is gated separately. gi_run_test is the one tool that executes a test exactly as saved, with nothing truncated — so in most accounts it posts to production. It needs GHOST_INSPECTOR_ALLOW_RUNS=true, which ALLOW_WRITES does not imply: an edit is recoverable from the backup the write path returns, a submitted form is not recoverable at all. On top of that, a test that submits is refused unless you confirm on that call. The check inlines modules first, since a test whose steps are only execute calls hides its submit inside one, and a chain that cannot be fully expanded counts as submitting.
Confirmation is asked for only where there is a consequence, which is the point — a flag every call needs is a flag every caller sets by reflex. Measured across a sample of real tests, roughly three quarters asked for confirmation and the rest ran without it — the ones that asked genuinely click a submit control.
Validation does not submit anything. gi_validate_test uses on-demand execution, which runs a definition and discards it, so nothing in your account changes. But it drives a real browser against a real URL, so two guards apply and neither can be turned off:
- Modules are inlined before anything is inspected. A test whose steps are only
executecalls hides its submit click inside a module, and guarding the definition as written would see nothing. Measured on a real account: of eight such tests, five would have posted a live form. - The run is truncated at the first step that could submit, and that step becomes an assertion on the same target — so the chain is verified, including that the submit control is reachable, without activating it. On a 30-test sample the guard fired on 25.
There is no option to make it submit; that stays a deliberate curl. Use dryRun first on anything touching production: it reports exactly what would run, inlined and guarded, without starting a browser or needing an organization id.
Development
174 tests, no test dependencies — Node's own runner and assert. They are organised by what breaks if the assertion fails, not by coverage, so a failure name tells you what you broke:
| File | What it pins |
|---|---|
config.test.js | The write gate opens for an exact true and not for 1 or yes; the key is re-read every call so rotation works; redact strips both the query parameter and a bare occurrence |
detail.test.js | The concurrency token reaches the caller; a module's missing verdict is not read as a failure; steps come back unexpanded so an edit targets the test that owns them |
create.test.js | A copy is silenced unless the caller insists — anything short of an explicit true still clears the schedule; a near-duplicate suite name is refused before it exists |
client.test.js | Truthy is not true; an unknown date reads as never-executed, because erring the other way slips a live module into a prune list; a stalled body download cannot outlive the request timeout |
graph.test.js | A cycle terminates and is still reported once shared subtrees stop being re-expanded; depth does not inflate on a level that adds nobody; hitting the documented nesting limit is reported rather than passed off as a total |
inventory.test.js | Every test lands in exactly one bucket; a module is never counted as failing; an empty suite still appears |
modules.test.js | The transitive radius exceeds the direct count; a cycle is a flag rather than an inflated number; a test that executes nothing is found |
diagnose.test.js | A step that never ran is not named as the failure; a resolved selector is not passed off as what the test looks for; a failing step from a module points at the module; a purged run is not reported as a test that never ran |
vacuous.test.js | A module is never called hollow however empty it looks; an assertion inherited from a module counts; a lone final assertion is shortlisted rather than condemned; an unreadable definition is skipped, not counted as empty |
repair.test.js | Rules that hold whatever the page contains are applied; a fragile selector is named but never rewritten, because inventing one would be a guess |
stale.test.js | The red pile splits with nothing lost; an unparseable date counts as changed; modules are excluded rather than evaluated |
validate.test.js | A submit inherited from a module is caught — guarding the definition as written was measured letting five of eight real tests post a live form; an import's condition gates every step it imports instead of being dropped |
run.test.js | Allowing writes does not allow running; a submit hidden inside a module still demands confirmation; a chain that could not be fully expanded counts as submitting |
writes.test.js | The direction of every uncertain case in the staleness guard; Ghost Inspector's own step defaults are not reported as differences; a field that only appears after the write is still an unexpected change |
server.test.js | The server starts, speaks the protocol, the write gate holds end to end, and every tool's annotations state the posture the code enforces |
server.test.js starts the real server over stdio, which is the only way to catch a registration or schema mistake. No API key is configured anywhere in the suite, so nothing reaches Ghost Inspector and the tests are safe to run against any machine.
CI runs the lot on Node 18, 20, 22 and 24 — the floor in engines plus both LTS lines and current, since npx runs on whatever Node the user already has. A second job re-runs the leak audit over the entire history rather than the working tree, because a leak scrubbed in a later commit is still in the history.
One limit worth stating. The API behaviours documented here were verified empirically against a single account on a single plan. They held every time they were checked, but a different plan could differ — if something contradicts this on your account, that is worth an issue.
Contributing
Issues and PRs welcome, but this is maintained on a best-effort basis — a tool built to solve a real problem, not a supported product. Changes are listed in CHANGELOG.md; anything security-relevant goes through SECURITY.md rather than a public issue.
No organization-specific data in code, tests, docs or examples: no ids, hostnames, folder or suite naming conventions, or test-data identities. All of that belongs in the caller's configuration. Use obvious placeholders like https://example.com and jane@example.com.
License
MIT. See LICENSE.
Ghost Inspector is a trademark of its respective owner. This project is unaffiliated.