# io.github.mockzilla/mockzilla-mcp (npm · @mockzilla/mcp)

Mockzilla MCP server. Mock any OpenAPI spec locally with Claude, Cursor, or Gemini CLI.

- Trust score: 66/100 (medium)
- Change this week: −11
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@mockzilla/mcp`: 66/100 (this document), [markdown](https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp.md), [page](https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp)

## Channel facts

- Registry: `npm`
- Package: `@mockzilla/mcp`
- Version: `0.2.13`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - No production dependencies, so there is no dependency health to assess.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 71 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 68/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2689 tokens (~158/item across 17 items; 17 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 88/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 65% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add mockzilla-mockzilla-mcp -- npx -y @mockzilla/mcp
```

### Codex

```bash
codex mcp add mockzilla-mockzilla-mcp -- npx -y @mockzilla/mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mockzilla-mockzilla-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mockzilla/mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add mockzilla-mockzilla-mcp --command npx --arg -y --arg @mockzilla/mcp
```

### Hermes

```yaml
mcp_servers:
  mockzilla-mockzilla-mcp:
    command: "npx"
    args: ["-y", "@mockzilla/mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-07-31 (score 66, −11)

- [security regression] Malware scan: pass → unverified
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 77, +30)

- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 65
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail

### 2026-07-26 (score 47)

First indexed and scored.

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

## MCP tools (17)

### `check_cli` (~95 tokens)

Check whether the mockzilla CLI is available — either on the system PATH, in the bridge's own cache (~/.cache/mockzilla-mcp/), or via a `go run` invocation. Call FIRST when the user wants to try mockzilla locally. If nothing resolves, the response carries `install_options`; suggest `install_cli` to the user and ask them which method (download / go-install / go-run) they prefer.

### `install_cli` (~173 tokens)

Install the mockzilla CLI for this user. Three methods — ASK the user which one they want before calling:
  • download (recommended): fetch the prebuilt binary for this OS/arch from github.com/mockzilla/mockzilla releases (~38MB). Fast, no toolchain needed.
  • go-install: run `go install <module>@v<version>` to compile from source. Needs Go on PATH.
  • go-run: don't install at all — the bridge stores a `go run <module>@v<version>` invocation. First serve_locally compiles into Go's module cache; later runs are instant. Needs Go.
Files land in the bridge's own cache, never on system PATH; blow it away with `rm -rf ~/.cache/mockzilla-mcp`.

Input parameters:

- `method` (string)

### `serve_locally` (~406 tokens)

Start ONE mockzilla portable mock server on this machine that serves any number of APIs together — no mockzilla account needed. Pass `input` as a single spec path / directory / public https URL, OR an array of them to combine multiple APIs into the same server (each becomes a service mounted at /<service>/...). Returns {url, port, pid, services} once listening. Pair with `stop_locally(pid)` to clean up. Prefer this over `deploy_mock_from_*` whenever the user says 'try locally', 'experiment', or 'play with' — those tools create persistent hosted bundles, this one is ephemeral. The bridge only runs ONE local server at a time on purpose: if the user wants more APIs, stop the current server and restart with all of them in `input`.

If the user names a well-known API (stripe, twilio, github, openai, slack, etc.) WITHOUT providing a URL, recall the public OpenAPI spec URL from your training knowledge and pass that. Do NOT pass a catalog ID or slug from `list_catalog_products` — that catalog is for the HOSTED `deploy_mock_from_catalog` flow, its ids are not URLs. Examples of public OpenAPI URLs:
  • Stripe: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
  • Twilio: https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json/twilio_api_v2010.json
  • GitHub: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
  • Petstore: https://petstore3.swagger.io/api/v3/openapi.json

Input parameters:

- `input` (required): Spec file path(s), directory, or public OpenAPI URL(s). Pass an array to combine multiple APIs into one server.
- `port` (integer): Port to bind on. Omit or pass 0 to let the OS pick a free port.

### `call_endpoint` (~152 tokens)

Make an HTTP request to a URL and return {status, headers, body}. Use this to demonstrate a mock by hitting it after `serve_locally` (e.g. `http://localhost:PORT/openapi/pet/findByStatus`), to inspect the admin API (`/.services` returns the registered services, `/healthz` for liveness), or to verify a freshly-mocked endpoint works. Default scope is localhost only; pass `allow_remote: true` for arbitrary URLs (rare — the bridge isn't a general-purpose HTTP client).

Input parameters:

- `allow_remote` (boolean)
- `body`
- `headers` (object)
- `method` (string)
- `url` (string, required)

### `mock_endpoint` (~420 tokens)

Quickly mock a single HTTP endpoint without writing an OpenAPI spec. Pass `method` (default GET), `path` (the EXACT HTTP path the user described, including all segments), and the `response` body (object → JSON, string → text). The bridge writes the response into a managed static dir at ~/.cache/mockzilla-mcp/mocks/ and (re)starts a single shared mockzilla server pointing at it.

Pass `path` AS IS. Do NOT prepend or duplicate any segment. The bridge derives the service name from the first segment for internal grouping, but it does not change the URL the user hits. Examples:
  • User says `GET /pets/{id}` → call mock_endpoint with path=`/pets/{id}` → URL is http://HOST:PORT/pets/{id}
  • User says `POST /orders` → path=`/orders` → URL is http://HOST:PORT/orders
  • User says `GET /v1/users/me` → path=`/v1/users/me` → URL is http://HOST:PORT/v1/users/me

Path placeholders like `{id}` are stored as literal directory names — by default ALL placeholder values share the same response. To return different responses for specific values, call mock_endpoint again with a literal value (e.g. /pets/123).

Calling this multiple times accumulates endpoints in the same server — adding `POST /pets` after `GET /pets/{id}` keeps both. Mutually exclusive with `serve_locally`: stop any ad-hoc server first. See `mockzilla_docs_search('static directory')` for the underlying convention.

Input parameters:

- `content_type` (string): Override content type. Inferred from response type if omitted (object → application/json, string → text/plain).
- `method` (string)
- `path` (string, required): Path beginning with /. First segment is the service name.
- `response`: Response body. Object → JSON. String → text. Default {}.
- `status` (integer)

### `list_mock_endpoints` (~91 tokens)

List all endpoints currently mocked via `mock_endpoint`. Returns {endpoints: [{method, service, path, file}], server_url, ui_url}. If a managed server is running, `ui_url` is the mockzilla UI (opens in a browser, shows endpoints grouped by service plus request inspection). Suggest the UI to the user when they want to explore beyond what the agent can show in chat.

### `clear_mock_endpoints` (~69 tokens)

Wipe ALL mocks created via `mock_endpoint` and stop the managed server. Equivalent to `rm -rf ~/.cache/mockzilla-mcp/mocks` plus `stop_locally`. Use when the user wants to start fresh. Does not touch the mockzilla CLI binary or other bridge state.

### `stop_locally` (~45 tokens)

Stop the mockzilla server started by `serve_locally`. Takes no arguments — there's only ever one local server running. Returns {stopped: bool, pid?, reason?}.

### `mockzilla_docs_topics` (~79 tokens)

List the available mockzilla doc topics (e.g. 'usage/portable', 'middleware', 'config/service'). Call this once at the start of a session involving non-trivial mockzilla usage to know what knowledge is available; then call `mockzilla_docs_search` with a query or `mockzilla_docs_read` for a specific topic.

### `mockzilla_docs_read` (~98 tokens)

Return the full markdown for one mockzilla doc topic. Use this when the user asks a deep question about a specific area (middleware, contexts, codegen, config) and you want full context. For broader questions or when you don't know the right topic, use `mockzilla_docs_search` first.

Input parameters:

- `topic` (string, required): Topic name from `mockzilla_docs_topics` (e.g. 'middleware', 'usage/portable').

### `mockzilla_docs_search` (~102 tokens)

Search the mockzilla docs by keyword. Returns the top-scoring sections {topic, heading, snippet} so you can identify which topic to read in full. Use this BEFORE answering questions about mockzilla syntax, conventions, or features you're not 100% sure of — the docs are the source of truth, your training is not.

Input parameters:

- `limit` (integer)
- `query` (string, required): Free-text query, e.g. 'static directory layout'.

### `bridge_status` (~73 tokens)

Report the bridge's own version and check whether a newer one is on npm. Returns {bridge_version, bridge_latest, update_available, upgrade_steps}. Call this when the user asks 'is mockzilla-mcp up to date?', or proactively if a tool starts failing in a way that could be a stale-bridge issue.

### `discover_specs` (~100 tokens)

Scan a directory and report what mockzilla can do with it: top-level OpenAPI spec files (with title and endpoint count) plus any `static/` subdirs that mockzilla can auto-mock. Returns a `suggested_input` the agent can hand directly to `serve_locally`. Use this when the user says 'I have a folder of specs/files, what's in it?' or 'mock this directory'.

Input parameters:

- `dir` (string, required)

### `peek_openapi` (~77 tokens)

Summarise an OpenAPI spec without serving it. Returns {title, version, openapi_version, endpoint_count, paths}. Pass `input` as a file path or a public https URL. Use this when the user wants to know what's in a spec before deciding whether to serve or deploy it.

Input parameters:

- `input` (string, required)

### `info` (~115 tokens)

Print a JSON summary of a spec, URL, or .mockz package — title, version, OpenAPI version, endpoint count, and the full path list with operation IDs. Pass `input` as a local spec file, a public https URL, or a `.mockz` package (mockzilla unpacks and summarises it). Use this to look inside something before serving or deploying it, or to inspect what a package contains.

Input parameters:

- `input` (string, required): Spec file path, public https URL, or .mockz package.

### `simplify` (~320 tokens)

Simplify an OpenAPI spec: drop or reduce union types (anyOf/oneOf), strip x-* extensions, and optionally limit the number of optional properties per schema. Writes the simplified spec to disk and returns its path. Use this when a spec is too large or too complex to mock cleanly (deeply nested unions, hundreds of optional fields) — the output is a faithful subset the agent can hand to `serve_locally`.

Optional-property handling:
  • omit `optional` to keep every optional property
  • `optional: N` keeps exactly N per schema (0 drops them all)
  • `optional_min`/`optional_max` (must come together) picks a random count in that range per schema

Pass `config` for an oapi-codegen-dd codegen.yml when the user wants filter + overlay + prune applied before simplification.

Input parameters:

- `config` (string): Path to an oapi-codegen-dd codegen.yml. Applies filter + overlay + prune before simplification.
- `input` (string, required): Spec file path or public https URL.
- `optional` (integer): Keep exactly N optional properties per schema. Mutually exclusive with optional_min/optional_max.
- `optional_max` (integer): Range mode upper bound (use with optional_min).
- `optional_min` (integer): Range mode lower bound (use with optional_max).
- `output` (string): Where to write the simplified spec. Omit to write into ~/.cache/mockzilla-mcp/simplified/ and let the bridge pick a name.

### `pack` (~274 tokens)

Pack a directory of mockzilla services into a `.mockz` archive for easier distribution or sharing. The archive carries a manifest (name, description, mounts, modes, git source) so the runtime can register every service without re-walking the tree. Hand the resulting .mockz to anyone — they can serve it with `serve_locally`, even from a URL. Use this when the user wants to share a working mock setup, snapshot one for a teammate, or publish it.

Defaults: output is `<basename>.mockz` next to `dir`. Git metadata (remote, ref, commit) is auto-embedded when `dir` is inside a git tree — pass `skip_git: true` to suppress.

Input parameters:

- `description` (string): Free-text description embedded in the manifest.
- `dir` (string, required): Directory containing services / specs to pack.
- `min_version` (string): Minimum mockzilla version required to load this archive (e.g. '2.5.3'). Useful when the archive relies on newer features.
- `name` (string): Display name embedded in the archive manifest.
- `output` (string): Output .mockz path. Defaults to <basename>.mockz next to dir.
- `skip_git` (boolean): Don't auto-embed git remote/ref/commit in the manifest.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp#diagnostics

## Score history

- 2026-08-03: 66
- 2026-08-02: 66
- 2026-08-01: 66
- 2026-07-31: 66
- 2026-07-29: 77
- 2026-07-28: 77
- 2026-07-27: 77
- 2026-07-26: 47

## Links

- npm package: https://www.npmjs.com/package/@mockzilla/mcp
- Socket report: https://socket.dev/npm/package/@mockzilla/mcp
- Repository: https://github.com/mockzilla/mockzilla-mcp
- Website: https://mockzilla.org/
- Changelog RSS feed: https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/mockzilla-mockzilla-mcp/mockzilla-mcp