Claude Media
RabbitMQのMCPサーバーでClaudeからキューとExchangeを操作する
Claude CodeMCPClaude連携チュートリアル

RabbitMQのMCPサーバーでClaudeからキューとExchangeを操作する

AWSのamazon-mq組織が公開するmcp-server-rabbitmqを使い、キュー深さの監視やデッドレターキュー調査を自然言語でClaudeに任せる手順とセキュリティ設計を扱います。

読了目安 約15分

RabbitMQ MCPサーバーとは何か

mcp-server-rabbitmqは、RabbitMQブローカーの管理・運用操作をMCP経由でAIエージェントに公開するサーバーです。GitHubのamazon-mqorganization配下でApache-2.0ライセンスで公開されているPython製ツールで、対象はRabbitMQブローカーの管理操作です。READMEの接続例はrabbitmq.example.comのような一般的なホスト名で、Amazon MQに限定した書き方ではありません。

解決する場面は、キューの詰まりやデッドレターキュー(処理に失敗したメッセージの退避先)の調査です。管理画面を何度も行き来して原因を探す作業を、自然言語の依頼に置き換えます。ツールはv4で31個、v3で61個あり、複数ツールを組み合わせた16種類の「スキル」(定型の調査手順)が付いています。

導入前に確認すること

  • Python 3.10以上(uv経由での実行が推奨)
  • 接続先のRabbitMQブローカー(AMQPエンドポイントとManagement APIの両方への到達性)
  • Claude CodeまたはClaude Desktopなど、MCPクライアントとして動く環境
  • 書き込み系操作(キュー作成・削除・rebalanceなど)を使う場合は、ブローカー側のRabbitMQユーザーに相応の権限があること

パッケージはamq-mcp-server-rabbitmqという名前でPyPIに公開されており、pip installまたはuvxでそのまま実行できます。

v3とv4、どちらを選ぶか

このサーバーはツールレイアウトが異なる2つのバージョン系列を同じリポジトリから配布しています。

バージョンツール数呼び出し方向いている場面
v3(3.x系)ツール数61(操作ごとに1ツール)呼び出し方rabbitmq_broker_list_queuesのような専用ツール名向いている場面v2系からの既存プロンプト・連携をそのまま使いたい
v4(4.x系)ツール数31(enumベースのディスパッチャ)呼び出し方queues(action="list")のようにactionを渡す向いている場面ツール説明文のトークン消費を抑えたい、--tool-groupsで必要な機能だけ絞りたい

v4ではREADMEによると、ツール名と説明文の合計が約2,300トークンから約900トークンに減ります。

パッケージを最新化しても既定ではv3互換の挙動のままで、--v4を明示しない限り既存の連携は壊れません。移行期は--v1-compatを付けると、v4のツールに加えてv3の旧ツール名もエイリアスとして登録されます。プロンプトの書き換えを急がずに済みます。

Claude Codeに接続する

Claude Codeでは、claude mcp addでstdio型のサーバーとして登録します。claude mcp add --helpには、環境変数を渡す-e, --envと、--の後ろにサーバー起動コマンドを置く形が例として出ています。

手順

Claude Codeへの登録手順

  1. 1

    パッケージを入れておく

    pip install amq-mcp-server-rabbitmq

    uvxで毎回実行する構成なら、事前のインストールは不要です。

  2. 2

    接続先を環境変数で渡して登録する

    claude mcp add rabbitmq \
  -e RABBITMQ_AMQP_ENDPOINT=amqps://admin:pass@broker.example.com:5671 \
  -- uvx amq-mcp-server-rabbitmq@latest --v4

    登録先は-s, --scopeで選びます。--helpにはlocal・user・projectの3つが並び、既定はlocalです。

  3. 3

    調査用の依頼を投げる

    Claude Codeを起動し、「キューの一覧を出して、メッセージが溜まっているものを教えて」のように頼みます。書き込み系のツールはこの時点では読み込まれません。

Claude Desktopの設定ファイルに書く場合は、v4モードで書き込みツールも許可した次の形です。

{
  "mcpServers": {
    "rabbitmq": {
      "command": "uvx",
      "args": [
        "amq-mcp-server-rabbitmq@latest",
        "--v4",
        "--allow-mutative-tools"
      ]
    }
  }
}

接続先の渡し方は2通りある

くらべる

接続先ブローカーの渡し方

既定

connectツールで都度接続

セッション内でエージェントがconnectツールを呼び、ホストとユーザー名を指定します。READMEの例では「Connect to my RabbitMQ broker at rabbitmq.example.com with user admin」と頼む形です。OAuthトークンで繋ぐ場合は、専用のOAuth接続ツールを使います。

再起動される構成向け

環境変数で起動時に接続

RABBITMQ_AMQP_ENDPOINTを設定すると、サーバーが起動時に接続します。MCPホストがセッションやツール呼び出しのたびにプロセスを作り直す構成(アグリゲータやプロキシ経由)でも、毎回「No active broker」で失敗しません。ただし、この環境変数ではOAuthは使えません。

エンドポイントURIのスキームが、TLSの有無とデフォルトポートを決めます。amqpsはTLSで5671、amqpは平文で5672です。Management APIはhttpsが443、httpが15672で、:portを明示すればそちらが優先されます。

片方の環境変数だけでも足ります。RABBITMQ_AMQP_ENDPOINTだけを渡せば、Management APIの接続先は同じホストと認証情報から導かれます。Management APIが別ホストや別の認証情報なら、RABBITMQ_MANAGEMENT_ENDPOINTも設定します。

認証情報に@や/のような予約文字を含む場合はパーセントエンコードが必要です。たとえばp@ss/wordはp%40ss%2Fwordと書きます。接続に失敗しても(到達できないブローカー、URIの書式ミス)サーバーは落ちず、警告をログに出してconnectツールを使える状態で残ります。

キュー深さの監視とデッドレターキュー調査

読み取り専用のツール群だけでも、日常的な運用監視の大半はカバーできます。queue_metrics_analysisスキルは、get_queue_infoが返すpublish/deliverレートとバックログの推移を読み、「このキューは処理が追いついていない」といった判断材料にします。resource_headroom_checkは、ノードのメモリ・ディスクの余裕率を使ってアラームまでの時間を見積もります。

デッドレターキュー(DLQ)調査には3つのスキルが対応します。

  • trace_dead_letter_chain:各キューのx-dead-letter-exchange引数を辿り、DLXの接続関係を地図にする
  • inspect_dead_letters:DLQ内のメッセージを覗き、x-deathヘッダーから元のキュー名と失敗理由を取り出す
  • dlq_summary:元のキューと拒否理由ごとに、デッドレターの件数を集計する

dlq_summaryは複数のツールを順に呼ぶ手順で、エージェントの内部では次の順に進みます。

手順

dlq_summaryが内部で踏む順序

  1. 1

    キューを洗い出す

    list_queuesで、.dlqで終わるキューやデッドレター関連の引数を持つキューを探します。

  2. 2

    深さを測る

    見つけたキューごとにget_queue_infoを呼び、メッセージ数を取ります。

  3. 3

    中身を覗く

    get_messagesでx-deathヘッダーを読み、元のキューと拒否理由を集めます。

結果は、DLQの本数・メッセージ総数・キューごとの内訳といった要約で返ります。docsの例では「orders.dlqが380件(理由はmax-retriesによる拒否)、payments.dlqが30件(期限切れ)」のような形です。管理画面でメッセージを1件ずつ開いて読み解く作業が、依頼1つになります。

  • 「注文キューのデッドレターを要約して、どのキューが原因になっているか教えて」
  • 「クラスタ全体でディスク使用率が閾値に近いノードはある?」
  • 「exchange-ordersからrouting key order.created を投げたら、どのキューに届く?」(trace_message_routeスキル)

スキルの正体と、読み取りで済む範囲

スキルはサーバーに組み込まれたコードではなく、手順を文章で記した「レシピ」です。エージェントがget_skillツールでレシピを取得し、stepsに沿って既存のツールを自分で呼びます。docsには、レシピは既存ツールの上に載る案内にすぎず、追加してもサーバーの書き込み権限の範囲は広がらないと書かれています。

読み取りの範囲に収まる動きは、次のとおりです。

  • get_messagesはキューのメッセージを消費せずに覗くツールで、DLQの中身を見ても取り出し済みにはなりません
  • trace_message_routeはExchangeのバインディングから届き先を予測するスキルで、実際にメッセージを送る操作ではありません
  • find_orphaned_queuesはバインディングもコンシューマーも持たないキューを探し、find_unbound_exchangesは出口のバインディングがないExchangeを探します

トポロジーを図で見たいときはexport_topology_graphでMermaid形式の図を出せます。broker_recommendationsはブローカーの現状とベストプラクティスの指針を突き合わせ、policy_conflict_detectionは重なり合うポリシーのパターンと優先順位の勝者を報告します。

書き込み操作は既定で無効

キューの作成・削除やvhost管理、接続の強制切断といった変更を伴う操作は、--allow-mutative-toolsを明示的に渡さない限り一切ロードされません。ツールグループ(v4)ごとの扱いは次のとおりです。

グループ主なツールロード条件
core主なツールconnect、get_skill、get_guidelineロード条件常にロード
read主なツールqueues、exchanges、connections、cluster、policiesロード条件常にロード
health / observability主なツールhealth、find_queuesロード条件常にロード
mutative主なツールmanage_queue、manage_exchange、publish、close_connectionロード条件--allow-mutative-toolsが必要
migration主なツールdefinitions_export、definitions_import、federation_setupロード条件--allow-mutative-toolsが必要

close_connectionとrebalance_queuesは、影響が大きいため単独のツールとしてmutativeグループに置かれています。監視専用のエージェントなら、--tool-groupsで読み込むグループを絞れます。

uvx amq-mcp-server-rabbitmq@latest --v4 --tool-groups read health

READMEのセキュリティ節には、書き込みの制御以外に次の設計が並んでいます。

  • TLSが既定: 接続はuse_tls=True・ポート5671を使い、TLSなしの接続にはレスポンスに警告が付く
  • SSRF対策: プライベートや予約済みのIP範囲、localhostへの接続はホスト名検証でブロックされる
  • 認証情報のマスキング: ブローカー定義のエクスポートでは、パスワードなど機微な項目が取り除かれてからエージェントに返る
  • 名前のURLエンコード: キュー・Exchange・vhostの名前は、API呼び出し前にURLエンコードされる

開発節にはdocker-composeでRabbitMQ 4をlocalhost:5672で起動する手順があり、ローカル検証用の既定の資格情報はguest / guestです。一方でセキュリティ節はlocalhostへの接続をブロックすると書いているため、手元のブローカーに繋ぐ際は警告やエラーの文言を見て挙動を確かめます。

本番ブローカーに繋ぐなら、まず--allow-mutative-toolsなしで調査と監視だけを任せ、変更までエージェントに任せたくなった段階でフラグを足す順序が安全です。

複数のブローカーを切り替えて使う

サーバーは複数のブローカーへの接続を同時に持てます。接続ごとに好きな別名(source、target、prod-uw2など)を付け、アクティブなのは常に1つです。切り替えには、v3ならrabbitmq_broker_select、v4ならbrokerツールを使います。切り替えても他の接続は切れません。

環境変数で接続する場合、別名の既定はホスト名で、RABBITMQ_ALIASで変えられます。ブルーグリーン移行(新旧2つのブローカーを並行稼働させて切り替える手法)では、この2接続が前提になります。

migrationグループを有効にすると、移行向けのスキルが使えます。pre_flight_migration_checkは両ブローカーでアラーム状態を確認し、定義を比較して切り替えの可否を判定します。migrate_definitionsは、変換ルールを適用しながらエクスポートとインポートを一度に実行します。

チームで共有するリモートサーバーとして動かす

ここまでのuvx起動は、MCPクライアントが子プロセスとして起動するstdio接続が前提です。チームで1つのサーバーを共有したい場合は、--httpでStreamable HTTPトランスポートに切り替えます。

uvx amq-mcp-server-rabbitmq@latest --v4 --http --server-port 8888 \
  --http-auth-jwks-uri https://your-idp.example.com/.well-known/jwks.json \
  --http-auth-issuer https://your-idp.example.com/ \
  --http-auth-audience rabbitmq-mcp \
  --http-auth-required-scopes "rabbitmq.read rabbitmq.write"

認証は独立した2層に分かれています。1層目はサーバーからRabbitMQへの認証(ユーザー名とパスワード、またはOAuthトークン)で、2層目はMCPクライアントからこのサーバーへの認証です。stdioで手元から使うなら1層目だけで足り、--httpで公開する場合に2層目が加わります。

2層目では、社内のIdP(IDプロバイダ)が発行するJWTをJWKS経由で検証します。docsによると、検証できるのはRS256署名のJWTです。JWKSは5分キャッシュされ、検証に失敗するとキャッシュを一度捨てて再試行するため、IdP側の鍵のローテーション直後でもトークンが弾かれません。iss・aud・必要なスコープは、フラグで指定したものだけが強制されます。

--http-auth-jwks-uriにHTTPS以外のURIを渡すと拒否されます。トークン検証をバイパスされる経路を塞ぐ設計です。設定中に拒否の理由(発行者の不一致、audienceの不一致、スコープ不足、期限切れ)を見たいときは、FASTMCP_LOG_LEVEL=DEBUGを付けます。

リモートサーバー化した瞬間に、ネットワーク上の誰かがブローカーへ到達できる経路が生まれます。認証フラグを省いた状態での公開は避けてください。

よくあるつまずき

  • 「No active broker」と毎回言われる: セッションごとにプロセスが再起動される構成では、RABBITMQ_AMQP_ENDPOINTによる起動時接続に切り替えます
  • v3向けに書いたプロンプトがv4で動かない: --v4を付けた瞬間に、ツール名がrabbitmq_broker_list_queues形式からqueues(action="list")形式に変わります。--v1-compatでv3の旧ツール名を併存させ、書き換えを段階的に進めます
  • 書き込み系ツールを頼んだのに動かない: --allow-mutative-toolsがないと、キュー作成やポリシー変更のツールはそもそもロードされません。意図的な安全策なので、必要な場面だけ付けます
  • 認証情報に含めた記号でエンドポイントURIが壊れる: パスワードに@や/を含む場合はパーセントエンコードが必須です。し忘れると、ホスト名やポートの解釈がずれて接続に失敗します
  • --management-portを指定したのにTLSで繋がらない: このフラグが上書きするのはManagement APIの既定ポート(TLS時443、非TLS時15672)だけです。TLSの有無はAMQPエンドポイントのスキーム(amqpsかamqp)で決まります

まとめ

読み取り専用の既定のまま監視とDLQ調査を始め、書き込みが必要になった時点で--allow-mutative-toolsを足す順序なら、本番ブローカーでも影響範囲を段階的に広げられます。チームで共有するときは、サーバー側のJWT検証まで含めて2層の認証を組みます。

MCPの基礎から確認したい場合はMCPとは何か、claude mcp addのスコープや認証の詳細はClaude Code MCP設定ガイド、ツールごとの許可・拒否ルールはClaude Code MCP権限ルールにまとめています。セルフホスト環境からMCPサーバーを届ける経路の選び方はClaude Codeセルフホスト環境にMCPサーバーを届ける3つの経路も参考になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →