Postman MCPサーバーの使い方 — ClaudeとClaude Codeでつなぐ3経路

PostmanをClaudeで使うには、公式のPostman MCPサーバーにつなぎます。Postman MCPサーバーは、ワークスペース・コレクション・仕様・モック・モニターといったPostmanのリソースを、AIエージェントへの自然言語の指示で操作できるようにする公式サーバーです。経路はClaudeアプリならConnector、Claude CodeならPluginかclaude mcp addでの手動接続です。どれを選ぶかで、ツール構成を選べるかどうかと、設定ファイルに何が残るかが変わります。

Claude CodeでのMCPサーバー追加構文とスコープの基礎はClaude Code MCP設定ガイド、MCPプロトコル自体の仕組みはMCPとはが扱っています。

Postman MCPサーバーとは

Postman MCPサーバーとは、Postman APIをMCPのツール群としてラップし、AIエージェントが自然言語でコレクションの実行やワークスペースの管理を行えるようにする公式サーバーです。リモート(ホスト型。ストリーマブルHTTP)とローカル(STDIOで自前起動)の2方式があり、npmパッケージ@postman/postman-mcp-serverとDockerイメージでも配布されています。

対応するAIエージェントはClaude・Cursor・VS Code(GitHub Copilot)・Codex CLIなど複数あります。

3つの接続経路とどれを選ぶか

Connectorは公式のPostmanコネクタページから追加します。ClaudeアプリとClaude Codeのどちらで何を動かすかが決まっていれば、迷う場面は少ない選択です。

ツール構成は5種類ある

リモートでもローカルでも、ロードするツールの範囲を次の5構成から選べます。ツールを絞るとトークン使用量が下がり、エージェントが適切なツールを選びやすくなります。

Context Graphは、どのAPI・サービスが存在し、何を公開し、互いにどう依存しているかを自然言語で尋ねる構成です。利用にはチームでContext Graphを有効にしておく必要があります。

エンドポイントのパスは構成名と一致しない点に注意が必要です。Fullだけ/fullではなく/mcpで、それ以外は/minimal・/code・/learn・/context-graphになります。EU向けはmcp.postman.comをmcp.eu.postman.comに置き換えます。ローカルサーバーでは、同じ構成をコマンド末尾のフラグ(--code・--full・--learn・--context-graph、Minimalはフラグなし)で切り替えます。

Claude Codeにコマンドで接続する

USリモートサーバーはOAuthに対応しています。Claude CodeはOAuthを自動で使うので、鍵を用意せずに追加できます。

claude mcp add --transport http postman https://mcp.postman.com/minimal

APIキー認証にするときは--headerフラグで渡します。EUリージョンはOAuthに非対応で、APIキー認証のみです。

claude mcp add --transport http postman https://mcp.eu.postman.com/mcp \
  --header "Authorization: Bearer <POSTMAN_API_KEY>"

設定ファイルに何が書かれるか

-s projectを付けてclaude mcp addを実行すると、カレントフォルダに.mcp.jsonができます。OAuth版とAPIキー版、ローカルのCode構成を続けて追加した例は次のとおりです。

{
  "mcpServers": {
    "postman": {
      "type": "http",
      "url": "https://mcp.postman.com/minimal"
    },
    "postman-eu": {
      "type": "http",
      "url": "https://mcp.eu.postman.com/mcp",
      "headers": {
        "Authorization": "Bearer <POSTMAN_API_KEY>"
      }
    },
    "postman-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["@postman/postman-mcp-server@latest", "--code"],
      "env": {
        "POSTMAN_API_KEY": "<POSTMAN_API_KEY>"
      }
    }
  }
}

注目点はAPIキーの扱いです。追加時の画面にはAuthorizationが[REDACTED]と表示されますが、ファイルには値がそのまま書かれます。-s projectで作る.mcp.jsonはリポジトリに入れてチームで共有する前提のファイルなので、キーを直書きしたままコミットすると漏れます。

Claude Codeの.mcp.jsonは${VAR}形式の環境変数展開に対応していて、headersとenvにも使えます。キーは"Authorization": "Bearer ${POSTMAN_API_KEY}"のように環境変数側に置き、ファイルには参照だけを残す形にできます。なお、OAuthで足りるUSリモートなら、保存すべき秘密情報自体がありません。

Postmanのプラグインでスキル込みで導入する

Postman公式のプラグインはpostmanlabs/postman-pluginで公開されています。以前のPostman-Devrel/postman-claude-code-pluginは非推奨になり、更新が止まった読み取り専用の状態です。旧リポジトリの案内は新リポジトリへの移行を指しています。

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install postman@claude-plugins-official

1行目はAnthropic公式マーケットプレイスの登録です。サインインを済ませた対話セッションを一度も開いていないClaude Codeには登録されていないため、この行が要ります。登録済みの環境では何も起こりません。

npx @postman/postman-pluginを実行すると、マシン上で見つかったエージェントの全部に一括で導入されます。対象はAntigravity・Claude Code・Codex・GitHub Copilot CLI・Cursor・Factory Droid・Kimi Code・OpenCode・Piです。statusで導入状況の確認、removeで削除、--agent <id>で対象を1つに絞れます。

現行のプラグイン(manifestはバージョン2.1.0)の中心は、Postmanの資源をファイルとして扱う作り方です。コレクションはpostman/collections/以下のディレクトリツリーで、リクエスト・フォルダ定義・保存済み例のそれぞれが1つのYAMLファイルになります。環境はpostman/environments/以下です。巨大なエクスポートJSONを書き換えずに1リクエストだけを読み書きでき、差分も小さくなるため、Gitとコードレビューの流れに載せやすくなります。

同梱されるスキルは17個で、名前から用途が分かります。

• 設計とテスト: api-testing / api-mocking / api-simulation / webhook-testing / api-documentation / api-engineer
• 運用: api-monitoring / ci-integration / performance-testing / flows / datasets / variables
• 調査: api-discovery / ai-readiness
• 土台: bootstrap / collection-schema-v3 / postman-mcp-server

接続先のMCPサーバーは、既定でFull構成のhttps://mcp.postman.com/mcpです。READMEによれば、MCPはPostman CLIが動かないときのフォールバックとして登録されます。この経路のMCP呼び出しはPostmanに届き、CLIの--no-report-eventsのようなオプションでは止まりません。通信自体を避けたいなら、MCPサーバーを入れない選択になります。Claude Code全体の使い方はClaude Code完全ガイドにまとめています。

リモートとローカルの違い

ローカルサーバーをClaude Codeに足すコマンドは次の形です。

claude mcp add postman --env POSTMAN_API_KEY=<POSTMAN_API_KEY> -- npx @postman/postman-mcp-server@latest

EUリージョンでは末尾に--region euを付けます。環境変数POSTMAN_API_BASE_URLで直接指定する方法もあります。ホストが「サーバーが出力した文字列はすべてエラー」と扱う場合は、--quietで起動ログを抑えられます。

Postman MCPサーバーでできることの具体例

Postmanが挙げる主な用途は、コードとコレクション・仕様の同期、コレクションのドキュメント更新やコメント追加、ワークスペースと環境の作成・環境変数の管理、コードからの仕様作成とコレクション生成の4つです。実際の指示文の書き方は、Tipsページに載っている例が参考になります。

• 環境変数の更新 — 「Postman環境"Local"の変数baseUrlの値をhttp://localhost:8001に変更して」と書くと、エージェントが環境を探して値を書き換えます
• 仕様の作成と同期 — Django REST FrameworkのCustomer用CRUD APIから、OpenAPI定義の推測、ワークスペース"Customers"のID取得、Postman仕様の作成、コレクション生成までを1つの指示にまとめます
• ドキュメントの更新 — 「"Customer API Collection"の説明を"認証と権限が必要な顧客テーブルへのCRUD操作"に更新して」のように、変更後の文面をそのまま渡します。エージェントはコレクションを一覧してから名前で1件を取り、PATCH /collection/{collectionId}で更新しました
• 逆方向の変更 — Spec Hubで仕様にフィールドを足したあと、「仕様を取得してDjangoのモデルとシリアライザに反映して」と頼みます。設計を先に固めるチームが、バックエンドの実装を仕様に追従させる使い方です

使うときの注意点

Postmanが挙げるベストプラクティスは3点です。

• MCPサーバーを使うと明記する — LLMがcurlやPostman CLIで直接操作しようとすることがあります。プロンプトの冒頭に「Postmanのリソースを操作するときは、使えるPostman MCPサーバーを使うこと」と書いておきます
• 変更・削除は返答を確かめてから受け入れる — 更新や削除のような破壊的な操作では、エージェントが返した内容を検証します
• リソースIDを渡す — ワークスペース名だけだと、一覧取得から絞り込みまで複数回のリクエストが発生します。IDを渡せば1回です

APIキーはシークレットとして扱い、環境変数かホストのシークレットストアに保存します。

よくあるつまずき

OAuthが使えるのにAPIキーを設定してしまう

USリモートサーバーはOAuthが推奨経路で、APIキーの管理が要りません。--headerでキーを渡すのは、EUリージョンを使う場合かOAuthを避けたい事情がある場合に絞れます。

同じ名前でエンドポイントの違う定義が複数ある

Postmanのドキュメントのコマンド例は、リモートでもローカルでもサーバー名をpostmanにしています。同じ名前で異なるエンドポイントを複数のスコープに定義すると、claude mcp listと/mcpが競合を警告します。OAuthのサインインはエンドポイントごとに保存されるため、別の定義が読み込まれるプロジェクトでは、あらためてサインインが必要です。残したい定義以外はclaude mcp remove <name> --scope <scope>で消せます。

接続したはずなのにツールが見当たらない

まとめ

Claudeアプリだけで使うならConnector、Claude Codeで設計からCIまで任せるならPlugin、ツール構成・リージョン・秘密情報の置き場所を自分で決めたいなら手動接続という分け方です。APIキーを使う場合は、.mcp.jsonに値を直書きせず環境変数の参照にするところまでが設定です。