mockzilla-mcp

@mockzilla/mcp

Mockzilla 的 MCP 服务——这是一个面向 OpenAPI 规范的开源 API 模拟服务。让 Claude Code、Claude Desktop、Cursor 或 Gemini CLI 安装 Mockzilla、检查 OpenAPI 规范，并在几秒内启动逼真的本地模拟 API。本地使用无需账户。

源码：github.com/mockzilla/mockzilla-mcp

使用场景

• 本地 API 开发 - 无需真实后端或沙盒账户，即可模拟任意 OpenAPI 规范
• CI/CD 集成测试 - 流水线中无需外部依赖
• PSP 和支付 API 模拟 - 无需测试账户，即可在编辑器中模拟 Stripe、PayPal、Adyen
• 加密货币交易所 API 模拟 - 无需注册账户，即可模拟 Binance、Bybit
• 速率限制保护 - 开发时调用 OpenAI、Twilio，不消耗配额
• Agentic 工作流 - 让 Claude 或 Cursor 自动启动和管理模拟服务

两个平面

@mockzilla/mcp 向 MCP 客户端提供两个工具平面。

本地平面（无需账户）

在你的机器上运行，无需 Mockzilla 账户。

你可以让 Agent：

• 检查是否已安装 Mockzilla CLI，并将其安装到受管理的缓存目录中（不会更改系统 PATH）。
• 检查和 lint OpenAPI 规范，或扫描文件夹以查找规范。
• 简化过于庞大、不适合模拟的规范，或将服务打包为 .mockz 归档文件。
• 根据规范生成 Go 代码：模型、适用于 14 种路由器之一的服务端、客户端或 MCP 工具。
• 将任意 OpenAPI 规范作为便携式模拟服务在本地运行，并调用其端点。
• 无需规范即可模拟单个 HTTP 端点。
• 列出、停止和清除本地管理的模拟服务。

托管平面（登录一次即可）

让 Agent 登录，或提出托管服务相关需求。Agent 会调用 login 工具，浏览器打开 Mockzilla 登录页面，你可以选择一个组织，并授予只读或读写权限。桥接程序会在你的机器上保存登录状态，并自动续期。托管工具从一开始就会列出；登录前，Agent 会提示先登录。

之后，Agent 可以：

• 列出已部署的模拟实例。
• 浏览目录产品。
• 根据规范、URL 或目录包部署托管模拟服务。
• 等待部署完成并返回在线 URL。

登录前，只会提供本地平面。用户注册前，Agent 仍可协助探索 Mockzilla 并运行本地模拟服务。

示例提示词

配置好 mockzilla 作为 MCP 服务后，可以在 Claude Code、Claude Desktop、Cursor 或 Gemini CLI 中直接使用以下提示词。

本地平面（无需账户）

• “这台机器上安装了 mockzilla CLI 吗？”
• “帮我安装 Mockzilla。”
• “在本地启动 Petstore OpenAPI 规范，这样我就可以用 curl 调用它。”
• “https://example.com/openapi.yaml 提供了哪些端点？”
• “模拟 POST /checkout，让它返回 402 响应。”
• “列出你正在管理的模拟端点。”
• “停止你启动的模拟服务。”
• “为 openapi.yml 生成 Go 模型和 chi 服务端，输出到 ./api。”

托管平面（登录后）

• “帮我登录 Mockzilla。”
• “列出我已部署的模拟实例。”
• “向我展示目录产品。”
• “部署一个名为 stripe-test 的 Stripe 模拟服务，并提供在线 URL。”
• “根据这个 OpenAPI URL 在 mockzilla.org 上创建托管模拟服务。”

安装

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"]
    }
  }
}

编辑后重启 Claude Desktop。

Cursor

最简单的方法：前往 设置 -> MCP 服务器 -> 添加新的 MCP 服务器，并填写：

• 名称：mockzilla
• 命令：npx
• 参数：-y @mockzilla/mcp@latest

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

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

编辑后重启 Cursor。

Gemini CLI

一条命令，无需手动编辑 JSON：

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"]
    }
  }
}

编辑后重启 Gemini CLI。

为什么使用 @latest？

不使用 @latest 时，npx 会缓存首次解析到的版本，之后不会获取新发布的版本。指定 @latest 会让 npx 在每次启动时重新检查注册表，因此重启 Claude / Cursor / Gemini 即可升级。代价是启动时间增加约 200 ms。

本地工具

这些工具始终可用，且绝不会离开用户的设备。

设置和状态

• check_cli 在此设备上查找 Mockzilla：系统 PATH -> bridge 缓存 -> go run 调用。如果均未找到，则返回安装选项。

• install_cli 将 Mockzilla 安装到 ~/.cache/mockzilla-mcp/。安装方式：download（从 GitHub releases 下载预构建版本，默认）、go-install、go-run。绝不会修改系统 PATH。

• bridge_status 报告 bridge 的版本、检查 npm 上是否有更新的发布版本，并提供升级步骤。

OpenAPI 探索和文档

• info 汇总 OpenAPI 规范，不启动服务：{title, version, openapi_version, endpoint_count, paths}。也会读取 .mockz 包。

• lint 查找规范中无法被任何值满足的架构，以便在启动服务前发现有问题的规范：{clean, defect_count, defects}。

• discover_specs 扫描目录，查找 OpenAPI 规范和静态端点文件夹。返回供 serve_locally 使用的 suggested_input。

• mockzilla_docs_topics 按类别列出 Mockzilla 文档，并提供每个主题的标题和摘要。来自 mockzilla.org 的产品文档、引擎文档和 mockzilla-codegen 文档均随包提供，因此无需联网或登录。

• mockzilla_docs_read 返回一个或多个主题的完整 Markdown，或整个类别的内容。

• mockzilla_docs_search 在所有文档中按关键词搜索，并返回包含片段的热门章节。

重塑规范

• simplify 删除或简化联合类型、剥离 x-* 扩展，并可选择限制每个架构中的可选属性数量。将简化后的规范写入磁盘并返回其路径。

• pack 将目录中的服务打包为 .mockz 归档，供 serve_locally 启动服务，也可从 URL 启动。

生成代码

• generate 运行内置的 mockzilla generate mockzilla-codegen：根据规范生成 Go 模型，并按需生成服务端、客户端或 MCP 工具。如果文件夹中包含 codegen.yaml，则会读取该文件。此工具会写入文件、通过 dry_run 先列出文件，或通过 check 报告过期文件，同时提供规范中的错误和警告。需要 CLI 2.11.0 或更高版本。

本地模拟

• serve_locally 在空闲端口上启动可移植的模拟服务。接受规范文件、目录或公开的 https URL。返回 {url, port, pid, services}。对于单个规范，latency、errors、mount 和 context 可分别用于添加延迟、注入错误响应、更改挂载路径或设置替换值。

• stop_locally 停止由 serve_locally 启动的服务。

• call_endpoint 发起 HTTP 请求并返回 {status, headers, body}，以显示模拟的响应。仅限 localhost，除非设置了 allow_remote。

• mock_endpoint 无需 OpenAPI 规范即可快速模拟单个 HTTP 端点。将静态响应写入受管理的 mocks 目录，并（重新）启动共享服务。可通过 status 和 headers 设置失败响应，或设置带有实际响应体的重定向（例如，包含错误负载的 404，或带有 Location 的 201）；对于没有响应体的 204 或 304，可省略 response。需要 mockzilla 2.8.20 或更高版本。

• list_mock_endpoints 列出当前模拟的所有端点，以及运行中服务的 URL 和 Mockzilla UI URL。

• clear_mock_endpoints 清除所有模拟，并停止受管理的服务。

• request_history 列出运行中的服务已响应的请求：方法、URL、状态、内容类型、延迟，以及响应是否来自上游。传入 id 和 service，可查看单个请求的完整标头和响应体。读取服务自身的历史记录 API，因此无需账户。

• diagnose_requests 说明记录的流量存在什么问题，以及数据来源：按来源、状态和内容类型分类的明细，延迟 p50/p95/最大值，以及相关发现，例如上游失败后悄然回退到生成的模拟、挂载前缀错误导致的 404，或非 JSON 内容类型下的 JSON 响应体。

• setup_replay 为某个服务配置回放：先记录一次响应，然后对每个匹配的请求返回该响应。返回 recording_scope，说明每个端点以什么为键，因为如果没有匹配字段，对某个端点的每次调用都会共用一条记录。仅在桥接程序自身的 mocks 目录中写入 config.yml；对于你自己项目中的文件夹，则返回 YAML 内容及其存放位置。

• list_replays 列出某个服务的记录，以及每条记录用作键的请求值。

• check_github_deployable 判断某个仓库或文件夹是否可以部署模拟，并在无法部署时说明缺少什么。支持两种类型：可移植服务文件夹和代码生成的 Go 服务端。只读。

• list_github_repos 列出用户的仓库，并标记哪些已发布模拟，以便 Agent 询问要使用哪个仓库。

• publish_to_github 将模拟推送到用户自己的某个仓库，并让 Mockzilla action 在用户自己的主机上部署，地址为 https://<label>.api.mockz.io。label 为仓库名称；如果已被占用，则添加 -2、-3。无需 Mockzilla 账户：首次推送时会注册该仓库。会合并到现有的 services 文件夹，而非替换它，并且绝不会覆盖现有工作流。

• wait_for_github_deploy 等待工作流运行完成，并返回 action 报告的线上 URL。

• unpublish_from_github 下线模拟并释放模拟名额，也可选择同时删除仓库。

账户

• login 在浏览器中打开 Mockzilla 登录页面，用户可在其中选择组织，以及只读或读写权限。会立即返回登录链接。用户批准后，Agent 会再次调用托管工具。登录信息保存在 ~/.config/mockzilla-mcp/ 下，每个服务 URL 对应一份，并会自动续期。

• logout 撤销连接并删除已保存的登录信息。要切换组织或权限，请先登出再登录。

托管工具

@mockzilla/mcp 会从一开始就列出托管工具，并在你登录后将请求转发到 mockzilla.org 的 MCP 端点。截至本文撰写时，托管工具包括：

• get_context
• list_sims
• list_catalog_products
• deploy_mock_from_catalog
• deploy_mock_from_spec
• deploy_mock_from_url
• wait_for_deploy

如需查看实时工具列表，请参阅托管服务的文档或 MCP 注册表条目。

在没有浏览器的机器上（例如 CI 或远程服务），请设置 MOCKZILLA_TOKEN，使用从控制面板获取的 API 密钥，而不是登录。之后即可直接使用托管工具。

配置

环境变量	默认值	用途
MOCKZILLA_TOKEN	未设置	用于替代登录的 API 密钥（mz_*），适用于没有浏览器的机器。
MOCKZILLA_MCP_URL	https://platform.mockzilla.org/mcp	覆盖托管端点，例如，本地开发时使用 http://localhost:8000/mcp。
MOCKZILLA_NO_BROWSER	未设置	设置为 1 时，执行 login 不会打开浏览器；Agent 会显示链接。
MOCKZILLA_MCP_CLIENT_ID	https://mockzilla.org/mcp-client.json	login 使用的 OAuth 客户端 ID。仅在本地开发时覆盖，例如使用在本地服务上注册的客户端。
MOCKZILLA_BIN_VERSION	与 bridge 版本一致	为 install_cli 获取的 Mockzilla CLI 指定版本。
MOCKZILLA_MANAGED_PORT	2200	mock_endpoint 服务的首选端口。如果端口被占用，则回退到内核选择的端口。避免使用 3000（Next.js/React）、5173（Vite）、8080。如果 2200 不可用，请尝试 2400 或 4444。
MOCKZILLA_DOCS_DIR	未设置	从由 scripts/build.mjs 构建的另一份 docs/ 中读取文档，而非使用打包的文档。

文件

bridge 将 CLI 和模拟项保存在 ~/.cache/mockzilla-mcp/ 下，并将登录信息保存在 ~/.config/mockzilla-mcp/ 下：

~/.cache/mockzilla-mcp/
├── bin/mockzilla        # downloaded or go-installed binary
├── config.json          # { method, version, invocation? }
└── mocks/               # mock_endpoint persists static endpoints here
    └── services/
        └── <first path segment>/<rest of path>/<method>/
            ├── index.<ext>   # the response body
            └── meta.json     # status and headers, written only when set

~/.config/mockzilla-mcp/
└── credentials.json     # saved logins, one per server URL, readable only by you

• rm -rf ~/.cache/mockzilla-mcp 会重置 CLI 和所有模拟端点，但会保留登录信息。
• 只清除模拟项：rm -rf ~/.cache/mockzilla-mcp/mocks。
• 如需删除登录信息，请让 Agent 注销。这也会在 mockzilla.org 上撤销登录授权。
• 系统的 PATH 不会被修改，因此重置不会影响单独通过 brew 安装的 Mockzilla。

更新

建议通过以下方式保持最新：

1. 在 MCP 客户端配置中固定使用 @mockzilla/mcp@latest，以便 npx 在每次启动时重新检查注册表。
2. 定期重启 Claude Desktop / Cursor / Gemini。届时会获取新的 tarball。
3. 如果发现异常，请询问 Agent：“运行 bridge_status 并告诉我 @mockzilla/mcp 是否为最新版本。”

如果版本过旧，请运行：

npx clear-npx-cache @mockzilla/mcp

然后重启 MCP 客户端。

Mockzilla CLI 的版本由 bridge 固定（通过 lib/install.js 中的 MOCKZILLA_VERSION）。更新 bridge 会更新该固定版本；下次调用 install_cli 时，CLI 本身也会更新到最新版本。

开发

有关项目约定以及添加新工具的操作指南，请参阅 CLAUDE.md。

发布

此桥接有两个需要保持同步的注册表：npm（@mockzilla/mcp）和 MCP 注册表（server.json）。如果跳过第二个注册表，发现服务的客户端就会固定使用上一个 tarball。

通常的做法是在 package.json 中提升 version，合并，然后发布一个标记为 v<version> 的 GitHub 版本。这会同时更新两个注册表：请参阅下文的通过 GitHub Actions。

如需手动发布：

1. 在 package.json 中提升 version。

2. 运行：

   make publish-all
   

   这会：

   • 根据已发布的文档包以及固定 CLI 版本的引擎文档，构建 docs/ 和 hosted-tools.json。仅限维护者：这需要在 local.mk 中设置 DOCS_BUNDLE_CMD。
   • 运行冒烟测试：stdio 往返测试、针对模拟 OAuth 服务的登录测试、文档工具测试、使用真实 CLI 测试 mock_endpoint，以及行为检查，确保每个工具只报告服务实际执行的操作（依赖 CLI 的测试在未安装 CLI 时会跳过）。
   • 执行 npm publish，发布新的 tarball。
   • 将版本同步到 server.json。
   • 使用 Keychain 中的 GitHub 令牌登录 mcp-publisher（见下文）。
   • 对 MCP 注册表运行 mcp-publisher publish。

3. 提交 server.json 的版本更新。

如果只想更新一侧：

• 仅发布到 npm：运行 make publish。
• 仅发布到 MCP 注册表：运行 make publish-mcp（会先从 package.json 重新同步 server.json）。

mcp-publisher 必须位于 PATH 中（运行 brew install mcp-publisher，或参阅安装文档）。

MCP 注册表登录

注册表登录有效期为 5 分钟，因此 make publish-mcp 会在每次发布前登录。它会从 macOS Keychain 读取 GitHub 令牌，因为浏览器登录（不带令牌运行 mcp-publisher login github）无法以 io.github.mockzilla 的身份发布。

一次性设置：

1. 创建经典 GitHub 令牌，并授予 read:org 和 read:user 权限。

2. 将令牌存入 Keychain。命令会提示输入令牌：

   security add-generic-password -a "$USER" -s mcp-publisher-github -w
   

通过 GitHub Actions

发布标签与 package.json 匹配的 GitHub 版本会运行 .github/workflows/publish.yml，该工作流会构建文档、运行冒烟测试，并通过 provenance 发布到 npm。如果 npm 上已有该版本，则会跳过，因此在运行 make publish 后再运行也是安全的。

需要进行两项一次性设置：

• npm Trusted Publishing。 在 npmjs.com 上的包设置中，添加可信发布者：仓库为 mockzilla/mockzilla-mcp，工作流为 publish.yml。无需在任何地方存储令牌。
• AWS_ROLE_ARN 仓库密钥，将其设为 infra 的 live/aws/iam-github-oidc 输出 github_mcp_release_role_arn 的值。文档包仅存储在 S3 中——没有任何服务会提供它，而该存储桶前面的 CDN 会缓存一天——因此发布时会假定一个可读取该单个密钥的角色。

.github/workflows/publish-mcp.yml 会在同一版本发布时启动，并负责另一个注册表。如果 MCP 注册表已有该版本，则会跳过；否则会等待最多 10 分钟，直到 npm 上出现该版本，然后使用 GitHub OIDC 发布 server.json，因此无需令牌。也可以从 Actions 选项卡手动启动此工作流。

两个工作流会并行运行，而非按顺序运行。等待循环确保了这一做法安全，而且本来就必不可少：npm 接受 tarball 后，可能还无法立即读取它。

相关项目

• mockzilla.org - 托管式 API 模拟、每个 PR 的模拟 URL、GitHub Actions 集成
• mockzilla/mockzilla - 核心开源 API 模拟服务
• 文档 - 便携模式和代码生成模式的完整使用指南
• mockzilla/mockzilla-codegen - mockzilla generate 背后的 Go 代码生成器

许可证

版权所有 © 2026 至今

基于 MIT 许可证授权