@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

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

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:

1. Pin @mockzilla/mcp@latest in your MCP client config (see install snippets above) so npx re-checks the registry on every spawn.

2. Restart Claude Desktop / Cursor periodically — that's when the new version is fetched.

3. 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.