@mockzilla/mcp

MCP server for mockzilla. Lets agents like Claude Desktop and Cursor drive mockzilla on a user's behalf — and lets them help users try mockzilla without an account first.

The bridge exposes two planes of tools:

Local plane (no account): check whether the mockzilla CLI is installed, install it for the user (prebuilt binary, go install, or go run), peek at an OpenAPI spec, and run portable mock servers locally. Nothing leaves the user's machine.
Hosted plane (with account): proxied to mockzilla.org's MCP endpoint when MOCKZILLA_TOKEN is set. List sims, deploy bundles from the catalog, etc.

Without a token, the local plane is the entire surface — agents can still help users explore mockzilla before they sign up.

Install

Claude Code

One-liner, no config editing:

claude mcp add -s user mockzilla -- npx -y @mockzilla/mcp@latest

-s user installs it for your user account (available in every project). Drop -s user to scope to the current project only.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Cursor

Easiest: Cursor Settings → MCP Servers → Add new MCP server, fill in:

Name: mockzilla
Command: npx
Args: -y @mockzilla/mcp@latest

Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Gemini CLI

One-liner, no config editing:

gemini mcp add -s user mockzilla npx -y @mockzilla/mcp@latest

-s user writes to ~/.gemini/settings.json (available in every project). Drop -s user (or use -s project) to scope to the current directory's .gemini/settings.json.

Or edit the settings file directly:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "@mockzilla/mcp@latest"]
    }
  }
}

Restart the client after editing config.

Why @latest? Without it, npx caches the first resolved version and won't pick up new publishes. Pinning to @latest makes npx re-check the registry on every spawn, so a Claude Desktop / Cursor restart is enough to upgrade. Tradeoff: ~200ms extra startup.

What you can ask

Without a token (local plane):

"Is the mockzilla CLI installed?"
"Install mockzilla for me." (agent will ask: download / go-install / go-run)
"Spin up the petstore spec locally so I can curl it."
"What endpoints does https://example.com/openapi.yaml have?"
"Stop the mock you started."

With a token (hosted plane added):

"List the sims I have deployed."
"Show me the catalog products."
"Deploy a Stripe sandbox named stripe-test and wait for the live URL."
"Create a mock from this OpenAPI URL on mockzilla."

Tools

Local

Tool	Purpose
`check_cli`	Resolve mockzilla on this machine: system PATH → bridge cache → `go run` invocation. Returns install options if nothing matches.
`install_cli`	Install mockzilla into `~/.cache/mockzilla-mcp/`. Methods: `download` (prebuilt from GitHub releases, default), `go-install`, `go-run`. Never touches system PATH.
`serve_locally`	Start a portable mock server on a free port. Accepts a spec file, directory, or public https URL. Returns `{url, port, pid, services}`.
`stop_locally`	Stop a server started by `serve_locally`.
`peek_openapi`	Summarise a spec without serving it: `{title, version, openapi_version, endpoint_count, paths}`.
`mock_endpoint`	Quickly mock a single HTTP endpoint without an OpenAPI spec. Writes a static response into the managed mocks dir and (re)starts the shared server.
`list_mock_endpoints`	List all endpoints currently mocked, plus the running server's URL and the mockzilla UI URL.
`clear_mock_endpoints`	Wipe all mocks and stop the managed server.
`bridge_status`	Report the bridge's own version, check npm for newer publishes, and surface upgrade steps.
`mockzilla_docs_topics`	List the available mockzilla doc topics.
`mockzilla_docs_read`	Return the full markdown for one topic.
`mockzilla_docs_search`	Keyword search across all docs; returns top sections with snippets.

Hosted

Available when MOCKZILLA_TOKEN is set. Forwarded to mockzilla.org. See the hosted server's docs for the live tool list — at the time of writing it includes get_context, list_sims, list_catalog_products, deploy_mock_from_{catalog,spec,url}, and wait_for_deploy.

Configuration

Env var	Default	Purpose
`MOCKZILLA_TOKEN`	unset	Bearer token (`mz_oauth_` or `mz_`). Hosted tools are hidden when unset.
`MOCKZILLA_MCP_URL`	`https://mockzilla.org/mcp/`	Override the hosted endpoint (staging, self-hosted).
`MOCKZILLA_BIN_VERSION`	matches bridge version	Pin a specific mockzilla CLI version for `install_cli` to fetch.
`MOCKZILLA_MANAGED_PORT`	`2200`	Preferred port for the `mock_endpoint` server (mockzilla's standard). Falls back to a kernel-picked port if busy. Pick something out of the way — avoid 3000 (Next.js/React), 5173 (Vite), 8080. Try 2400 or 4444 if 2200 is unavailable.
`MOCKZILLA_DOCS_DIR`	unset	Read docs from this local directory instead of fetching from GitHub. Useful when editing docs and wanting instant feedback.
`MOCKZILLA_DOCS_REPO`	`mockzilla/mockzilla`	Override the GitHub repo to fetch docs from.
`MOCKZILLA_DOCS_BRANCH`	`main`	Override the branch to fetch docs from.

Cache

The bridge keeps everything under ~/.cache/mockzilla-mcp/:

~/.cache/mockzilla-mcp/
├── bin/mockzilla        # downloaded or go-installed binary
├── config.json          # {method, version, invocation?}
└── mocks/               # mock_endpoint persists static endpoints here
    └── static/
        └── <service>/<path>/<method>/index.<ext>

rm -rf ~/.cache/mockzilla-mcp resets the bridge fully (binary + all mocked endpoints). To wipe just the mocks: rm -rf ~/.cache/mockzilla-mcp/mocks. The system PATH is never touched, so reset doesn't affect a separate brew install.

Updates

The bridge ships frequently; recommended way to stay current:

Pin @mockzilla/mcp@latest in your MCP client config (see install snippets above) so npx re-checks the registry on every spawn.
Restart Claude Desktop / Cursor periodically — that's when the new version is fetched.
If something breaks, ask the agent: "Run bridge_status and tell me if mockzilla-mcp is up to date." If it's stale, run npx clear-npx-cache @mockzilla/mcp and restart your client.

The mockzilla CLI version is pinned by the bridge (MOCKZILLA_VERSION in lib/install.js). Updating the bridge updates the pin; the next install_cli call brings the CLI itself up to date.

Development

See CLAUDE.md for project conventions and a walkthrough of adding a new tool.

License

MIT.

mockzilla-mcp

Quick Install