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 を使った開発ができます
• エージェント型ワークフロー - Claude や Cursor にモックサーバーを自動的に起動・管理させることができます

2 つのプレーン

@mockzilla/mcp は、MCP クライアントに 2 つのプレーンのツールを公開します。

ローカルプレーン（アカウント不要）

お使いのマシン上で実行されます。Mockzilla アカウントは不要です。

エージェントから、次の操作ができます。

• Mockzilla CLI がインストールされているか確認し、管理対象のキャッシュにインストールします（システムの PATH は変更しません）。
• OpenAPI 仕様を調査してリンティングするか、フォルダー内の仕様をスキャンします。
• モックには大きすぎる仕様を簡素化するか、サービスを .mockz アーカイブにまとめます。
• 仕様から Go コードを生成します。モデル、14 種類のルーターのいずれかを使ったサーバー、クライアント、または MCP ツールを生成できます。
• 任意の OpenAPI 仕様をポータブルなモックサーバーとしてローカルで提供し、そのエンドポイントを呼び出します。
• 仕様なしで、単一の HTTP エンドポイントをモックします。
• ローカルで管理しているモックを一覧表示、停止、削除します。

ホスト型プレーン（1 回ログイン）

エージェントにログインを依頼するか、ホスト型の機能を依頼します。エージェントは login ツールを呼び出し、ブラウザーで Mockzilla のログイン画面が開きます。そこで組織を選び、読み取り専用または読み取り・書き込みのアクセス権を選択します。ブリッジはログイン状態をお使いのマシンに保持し、自動的に更新します。ホスト型ツールは最初から一覧に表示されます。ログイン前は、エージェントにまずログインするよう案内されます。

その後、エージェントは次の操作ができます。

• デプロイ済みのシムを一覧表示します。
• カタログ製品を閲覧します。
• 仕様、URL、またはカタログバンドルからホスト型モックをデプロイします。
• デプロイを待機し、稼働中の URL を返します。

ログイン前に公開されるのはローカルプレーンのみです。サインアップする前でも、エージェントは 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

最も簡単な方法は、Settings -> MCP Servers -> Add new MCP server を選択し、以下を入力することです。

• Name: mockzilla
• Command: npx
• Args: -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 に書き込みます（すべてのプロジェクトで利用できます）。
• 現在のディレクトリにある .gemini/settings.json に適用するには、-s user を省略するか、-s project を使用します。

または、設定ファイルを直接編集します。

{
  "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 → ブリッジのキャッシュ → go run の順に解決します。一致するものがない場合は、インストール方法を返します。

• install_cli Mockzilla を ~/.cache/mockzilla-mcp/ にインストールします。方法は download（GitHub リリースからのビルド済みバイナリ。デフォルト）、go-install、go-run です。システムの PATH は変更しません。

• bridge_status ブリッジのバージョンを報告し、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 1 つ以上のトピック、またはカテゴリ全体の Markdown を返します。

• mockzilla_docs_search すべてのドキュメントをキーワード検索し、スニペット付きの上位セクションを返します。

仕様の再構成

• simplify 共用体型の削除または簡略化、x-* 拡張の除去、スキーマごとのオプションプロパティ数の上限設定を行います。簡略化した仕様をディスクに書き込み、そのパスを返します。

• pack サービスのディレクトリを .mockz アーカイブにまとめます。URL からでも serve_locally で提供できます。

コードの生成

• generate 組み込みの mockzilla-codegen である mockzilla generate を実行します。仕様から 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} を返します。allow_remote が設定されていない場合は、localhost のみが対象です。

• mock_endpoint OpenAPI 仕様を使わずに、単一の HTTP エンドポイントをすばやくモックします。管理対象の mocks ディレクトリに静的レスポンスを書き込み、共有サーバーを（再）起動します。失敗レスポンスや、実際の本文を含むリダイレクト（エラーペイロード付きの 404、Location を含む 201 など）には status と headers を指定します。本文のない 204 または 304 の場合は response を省略します。mockzilla 2.8.20 以降が必要です。

• list_mock_endpoints 現在モック化されているすべてのエンドポイントと、実行中サーバーの URL および Mockzilla UI の URL を一覧表示します。

• clear_mock_endpoints すべてのモックを消去し、管理対象のサーバーを停止します。

• request_history 実行中のサーバーが応答したリクエストを一覧表示します。メソッド、URL、ステータス、コンテンツタイプ、レイテンシ、レスポンスがアップストリーム由来かどうかが含まれます。service とともに id を渡すと、1 件のリクエストの完全なヘッダーと本文を取得できます。サーバー独自の履歴 API を読み取るため、アカウントは不要です。

• diagnose_requests 記録されたトラフィックの問題点と、データの取得元を説明します。オリジン、ステータス、コンテンツタイプ別の内訳、レイテンシの p50／p95／最大値に加え、失敗したアップストリームが通知なく生成済みモックにフォールバックしたケース、マウントプレフィックスの誤りによる 404、非 JSON のコンテンツタイプに JSON 本文が含まれているケースなどを検出します。

• setup_replay サービスのリプレイを設定します。レスポンスを一度記録し、一致するすべてのリクエストに対してそのレスポンスを返します。各エンドポイントが何をキーにするかを示す recording_scope を返します。照合フィールドがない場合、あるエンドポイントへの呼び出しはすべて同じ記録を共有するためです。config.yml はブリッジ専用の mocks ディレクトリ内にのみ書き込みます。自分のプロジェクトにあるフォルダーを指定した場合は、YAML と保存先を返します。

• list_replays サービスの記録を、それぞれの記録のキーとなるリクエスト値とともに一覧表示します。

• check_github_deployable リポジトリまたはフォルダーがモックをデプロイできるかどうかと、できない場合に不足しているものを示します。ポータブルなサービスフォルダーと codegen Go サーバーの両方に対応しています。読み取り専用です。

• list_github_repos ユーザーのリポジトリを一覧表示し、すでにモックを公開しているものに印を付けることで、エージェントがどれを使うか尋ねられるようにします。

• publish_to_github ユーザー自身のリポジトリのいずれかにモックをプッシュし、Mockzilla アクションによってユーザー自身のホスト https://<label>.api.mockz.io にデプロイできるようにします。ラベルはリポジトリ名で、使用済みの場合は -2、-3 が付加されます。Mockzilla アカウントは不要です。最初のプッシュ時にリポジトリが登録されます。既存の services フォルダーは置き換えずに統合し、既存のワークフローを上書きすることもありません。

• wait_for_github_deploy ワークフローの実行を待ち、アクションが報告したライブ URL を返します。

• unpublish_from_github モックを停止してシミュレーション枠を解放します。必要に応じてリポジトリも削除できます。

アカウント

• login ブラウザーで Mockzilla のログインページを開き、ユーザーが組織と読み取り専用または読み書きのアクセス権を選択できるようにします。ログインリンクをすぐに返します。ユーザーが承認した後、エージェントはホスト型ツールを再度呼び出します。ログイン情報は ~/.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 やリモートサーバーなど、ブラウザーのないマシンでは、ログインする代わりにダッシュボードで取得した API キーを MOCKZILLA_TOKEN に設定してください。ホスト型ツールは起動時から利用可能になります。

設定

環境変数	デフォルト	用途
MOCKZILLA_TOKEN	未設定	ブラウザーのないマシンでログインの代わりに使用する API キー（mz_*）です。
MOCKZILLA_MCP_URL	https://platform.mockzilla.org/mcp	ホスト型エンドポイントを上書きします。例：ローカル開発用の http://localhost:8000/mcp。
MOCKZILLA_NO_BROWSER	未設定	1 に設定すると、login 時にブラウザーを開かず、代わりにエージェントがリンクを表示します。
MOCKZILLA_MCP_CLIENT_ID	https://mockzilla.org/mcp-client.json	login が使用する OAuth クライアント ID です。ローカル開発時のみ上書きしてください。例：ローカルサーバーに登録したクライアントを使用する場合。
MOCKZILLA_BIN_VERSION	ブリッジのバージョンと一致	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/ ビルドからドキュメントを読み込みます。

ファイル

ブリッジは 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 を実行してください。
• ログイン情報を削除するには、エージェントにログアウトを依頼してください。mockzilla.org 上のログイン情報も失効します。
• システムの PATH は変更されないため、リセットしても別途 brew でインストールした Mockzilla には影響しません。

更新

常に最新の状態に保つには、次の方法をおすすめします。

1. MCP クライアント設定で @mockzilla/mcp@latest を指定し、起動のたびに npx がレジストリを再確認するようにします。
2. Claude Desktop／Cursor／Gemini を定期的に再起動します。その際に新しい tarball が取得されます。
3. 問題があるように見える場合は、エージェントに「bridge_status を実行して、@mockzilla/mcp が最新かどうか教えてください」と依頼します。

古いバージョンを使用している場合は、次を実行してください。

npx clear-npx-cache @mockzilla/mcp

その後、MCP クライアントを再起動してください。

Mockzilla CLI のバージョンはブリッジによって固定されています（lib/install.js の MOCKZILLA_VERSION）。ブリッジを更新すると固定バージョンも更新され、次回の install_cli 呼び出し時に CLI 自体も最新になります。

開発

プロジェクトの規約と新しいツールの追加手順については、CLAUDE.md を参照してください。

リリース

このブリッジでは、npm（@mockzilla/mcp）と MCP レジストリ（server.json）の 2 つを同期させる必要があります。2 つ目を省略すると、検出クライアントは以前の 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 がインストールされていない場合はスキップされます）。
   • 新しい tarball を npm publish します。
   • バージョンを server.json に反映します。
   • Keychain に保存された GitHub トークンを使って mcp-publisher にログインします（下記参照）。
   • MCP レジストリに対して mcp-publisher publish を実行します。

3. server.json の更新をコミットします。

片方だけを公開する場合：

• npm のみの場合は make publish。
• MCP レジストリのみの場合は make publish-mcp（最初に server.json は必ず package.json と再同期されます）。

mcp-publisher が PATH に含まれている必要があります（brew install mcp-publisher を実行するか、インストールドキュメントに従ってください）。

MCP レジストリへのログイン

レジストリへのログインは 5 分間有効なため、make publish-mcp は公開のたびにログインします。ブラウザーからのログイン（トークンを指定しない mcp-publisher login github）では io.github.mockzilla として公開できないため、macOS Keychain から GitHub トークンを読み込みます。

初回のみ、次の設定が必要です。

1. read:org と read:user を指定してクラシック GitHub トークンを作成します。

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 の後に実行しても安全です。

実行するには、次の 2 項目を一度だけ設定する必要があります。

• 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 は 1 日間キャッシュするため、リリース処理では、その 1 つのキーを読み取れるロールを引き受けます。

.github/workflows/publish-mcp.yml は同じリリースをトリガーに起動し、もう一方のレジストリを担当します。MCP レジストリにすでに存在するバージョンはスキップし、バージョンが npm に反映されるまで最大 10 分間待ってから、GitHub OIDC を使って server.json を公開するため、トークンは不要です。Actions タブから手動で実行することもできます。

2 つのワークフローは順番ではなく並行して実行されます。安全性を保つのは待機ループであり、これはいずれにしても必要です。npm は tarball を読み戻せるようになる前に受け付けるためです。

関連項目

• mockzilla.org - ホスト型 API シミュレーション、PR ごとのモック URL、GitHub Actions 連携
• mockzilla/mockzilla - 中核となるオープンソースの API モックサーバー
• ドキュメント - ポータブルモードと codegen モードの完全な利用ガイド
• mockzilla/mockzilla-codegen - mockzilla generate の基盤となる Go コードジェネレーター

ライセンス

Copyright © 2026-present

MIT ライセンスの条件に基づきライセンスされています。