@mockzilla/mcp

mockzilla 的 MCP 服务器。允许像 Claude Desktop 和 Cursor 这样的助手代表用户驱动 mockzilla，并帮助用户在无需账户的情况下尝试 mockzilla。

该桥接器提供了两个层面的工具：

• 本地层面（无需账户）： 检查 mockzilla CLI 是否已安装，为用户安装它（预构建二进制文件、go install 或 go run），查看 OpenAPI 规范，并在本地运行便携式 Mock 服务器。所有操作均在用户本地机器上完成，不会泄露任何数据。

• 托管层面（拥有账户）： 当设置了 MOCKZILLA_TOKEN 时，代理到 mockzilla.org 的 MCP 端点。列出模拟环境、从目录部署包等。

如果没有令牌，本地层面就是全部功能——助手仍然可以在用户注册前帮助他们探索 mockzilla。

安装

Claude Code

一行命令，无需编辑配置：

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

-s user 将其安装到您的用户账户（在每个项目中均可用）。删除 -s user 可将其仅限于当前项目。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

Cursor

最简单的方法：Cursor 设置 → MCP 服务器 → 添加新 MCP 服务器，填写：

• 名称：mockzilla

• 命令：npx

• 参数：-y @mockzilla/mcp@latest

或者直接编辑 ~/.cursor/mcp.json：

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

Gemini CLI

一行命令，无需编辑配置：

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

-s user 会写入 ~/.gemini/settings.json（在每个项目中均可用）。删除 -s user（或使用 -s project）可将其限制为当前目录的 .gemini/settings.json。

或者直接编辑设置文件：

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

编辑配置后请重启客户端。

为什么要用 @latest？ 如果不使用它，npx 会缓存第一个解析的版本，而不会获取新发布的版本。锁定到 @latest 会使 npx 在每次启动时重新检查注册表，因此重启 Claude Desktop / Cursor 就足以进行升级。权衡：额外约 200ms 的启动时间。

您可以询问的内容

无需令牌（本地层面）：

• “mockzilla CLI 安装了吗？”

• “帮我安装 mockzilla。”（助手会询问：下载 / go-install / go-run）

• “在本地启动 petstore 规范，以便我可以用 curl 调用它。”

• “https://example.com/openapi.yaml 有哪些端点？”

• “停止你启动的那个 mock。”

拥有令牌（添加了托管层面）：

• “列出我已部署的模拟环境。”

• “向我展示目录产品。”

• “部署一个名为 stripe-test 的 Stripe 沙盒，并等待实时 URL。”

• “在 mockzilla 上从这个 OpenAPI URL 创建一个 mock。”

工具

本地

托管

当设置了 MOCKZILLA_TOKEN 时可用。转发到 mockzilla.org。请参阅托管服务器的文档以获取实时工具列表——在撰写本文时，它包括 get_context、list_sims、list_catalog_products、deploy_mock_from_{catalog,spec,url} 和 wait_for_deploy。

配置

缓存

桥接器将所有内容保存在 ~/.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 会完全重置桥接器（二进制文件 + 所有 Mock 端点）。仅清除 Mock：rm -rf ~/.cache/mockzilla-mcp/mocks。系统 PATH 从未被触碰，因此重置不会影响单独的 brew 安装。

更新

桥接器更新频繁；保持最新的推荐方法：

1. 在您的 MCP 客户端配置中锁定 @mockzilla/mcp@latest（见上文安装片段），以便 npx 在每次启动时重新检查注册表。

2. 定期重启 Claude Desktop / Cursor —— 这是获取新版本的时候。

3. 如果出现问题，请询问助手：“运行 bridge_status 并告诉我 mockzilla-mcp 是否是最新的。” 如果版本过旧，请运行 npx clear-npx-cache @mockzilla/mcp 并重启您的客户端。

mockzilla CLI 版本由桥接器锁定（lib/install.js 中的 MOCKZILLA_VERSION）。更新桥接器会更新锁定版本；下一次 install_cli 调用会将 CLI 本身更新到最新。

开发

请参阅 CLAUDE.md 了解项目规范和添加新工具的演练。

许可证

MIT。