band-mcp

BAND MCP

Claude を BAND に接続する Model Context Protocol サーバーです。BAND は、チーム、クラブ、クラス、家族が利用するグループアプリです。バンド、投稿、コメント、お知らせ、カレンダーの予定、メンバー、チャットを読み取ります。また、投稿やコメントの作成もできますが、どちらも確認が必要です。

警告

AI 開発プロジェクトです。 Claude がこのコードベースを構築し、保守しています。実装は人間による監査を受けていません。使用前に、すべてのコードとツールの権限を確認してください。

注意

非公式で、サポート対象外です。 BAND には公開 API がありません。このサーバーは、band.us のウェブアプリが使用する内部 API を、自分のログイン済みブラウザーセッションで認証して呼び出します。予告なく動作しなくなる可能性があり、自動利用は BAND の利用規約に抵触する場合があります。ご自身のアカウントで、ご自身の責任においてのみ使用してください。

できること

Claude に次のようなことを尋ねられます。

• 「BAND グループの新着情報は？」
• 「チームのバンドの来月までのカレンダーには何がある？」
• 「最新のお知らせへのコメントを要約して。」
• 「最近オンラインになっていないメンバーは誰？」
• 「木曜日の練習が午後6時に変更になったことを、バンドにリマインドとして投稿して。」

必要条件

• Claude Desktop、Claude Code、または任意の MCP ホスト
• Node.js 22.5 以降
• ContextMint Bridge ブラウザー拡張機能と、ログイン済みの https://www.band.us/ タブ

インストール

Claude Code プラグイン

claude plugin marketplace add chrischall/band-mcp
claude plugin install band@chrischall

このプラグインは band skill もインストールします。このスキルは、Claude にワークフローと確認フローを説明します。

任意の MCP ホスト（npx）

{
  "mcpServers": {
    "band": {
      "command": "npx",
      "args": ["-y", "@chrischall/band-mcp"],
      "env": { "MCP_USER_TZ": "America/New_York" }
    }
  }
}

Claude Desktop（.mcpb）

最新リリースから .mcpb バンドルをインストールします。任意の設定項目（タイムゾーン、書き込み確認モード、確認プロンプト、デバッグログ、ブリッジポート）は、設定の環境変数を指定します。デフォルト値を使う場合は空欄のままにしてください。

サインインの仕組み

BAND のウェブ API には、ブラウザーにしかない次の2つが必要です。band.us のセッション Cookie と、BAND がウェブページにのみ渡すセッションごとの署名キーです。ほかの場所から取得すると、署名キーは空で返されます。このサーバーは fetchproxy ブリッジ（ContextMint Bridge）を使用して、次の処理を行います。

1. ログイン済みのタブから band.us のセッション Cookie（セッショントークンと、docs/BAND-API.md に記載された5つの関連 Cookie）を読み取り、
2. そのタブ経由で署名キーを取得します。

その後、すべての API 呼び出しは Node から https://api-us.band.us に直接送信され、リクエスト URL の HMAC で署名されます。Cookie とキーはメモリ内にのみ保持されます。エラー、結果、ログに記録されることはありません。ホームディレクトリに書き込まれるのは、ブリッジのペアリング ID だけです。サーバーがパスワードを参照したり保存したりすることはありません。

band.us のセッションは数日間有効です。有効期限まで10分を切ると、サーバーはタブからセッションを再取得します。また、BAND から「未承認」と応答された場合も1回だけ再取得し、呼び出しごとに1回だけ再試行します。ブラウザーの外部でトークンを更新するとブラウザーからサインアウトされる可能性があるため、サーバーがセッションを自ら更新することはありません。呼び出しが失敗し始めたら、https://www.band.us/ を開くか再読み込みしてサインインしてください。ブラウザーがセッションを更新します。band_healthcheck ではセッションの残り時間を分単位で確認できますが、Cookie の値は表示されません。

ペアリング（一度だけ）

1. ContextMint Bridgeをインストールし、そのブラウザーでhttps://www.band.us/にサインインします。
2. Claudeにband_healthcheckを実行するよう依頼します。最初の呼び出しでペアリングコードが返されます。
3. ContextMint Bridgeのポップアップでそのコードを承認します。信頼情報は~/.fetchproxy/identity/に保存され、再起動後も維持されます。

ブラウザーを複数使っていますか？ band.usのセッションがあるブラウザーでコードを承認してください。サーバーは承認した拡張機能を固定します。refusing an extension whose identity is not the one this MCP paired withのようなstderrの行が表示されることがあります。これは別のブラウザーが拒否されたことを示すもので、問題ありません。

間違ったブラウザーとペアリングしましたか？ ContextMint Bridgeのポップアップでband-mcpの信頼を取り消します。次に、サーバーを再起動してからペアリングし直すために、@fetchproxy/cliからfpx trust clear band-mcpを実行します。

設定

環境変数	デフォルト	用途
BAND_WS_PORT	37149	fetchproxyブリッジのポートです。fetchproxyの全サービスとContextMint Bridgeは37149を共有します。ローカルテスト時、またはホストから登録ごとのポートが割り当てられる場合にのみ上書きしてください。
MCP_USER_TZ	システムのタイムゾーン	IANAタイムゾーンです。例：America/New_York。デバイスのタイムゾーンとしてBANDに送信され、band_list_eventsで「今日」の判定に使われます。ホスト環境ではサーバーがUTCで動作するため、設定してください。
BAND_DEBUG	オフ	ブリッジの役割とライフサイクルをstderrに記録します。
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアントで、書き込みをどのように処理するかを指定します。詳しくは以下をご覧ください。
MCP_CONFIRM_ELICITATION	on	offにすると確認プロンプトが表示されなくなり、すべてのクライアントでMCP_CONFIRM_MODEの動作が適用されます。プロンプトに対応していると宣言しながら、実際には表示しないクライアントで使用してください。

書き込みの確認

band_create_postとband_create_commentでは確認が必要です。

• MCPエリシテーションに対応したクライアントでは、バンド名とテキストが表示された実際の確認プロンプトが表示されます。
• その他のクライアント（claude.ai、Claude Desktop）では、最初の呼び出しで変更は行われません。プレビューと、1回限りで有効期間の短いconfirmTokenが返されます。そのトークンを付けて再度呼び出した場合にのみ、書き込みが行われます。その間にリクエストの内容が少しでも変更された場合、またはブラウザーで別のBANDアカウントにサインインした場合、トークンは拒否されます。

MCP_CONFIRM_MODEは、そのトークンを使用できるクライアントを決定します。

値	動作
ask-user（デフォルト）	トークンを再利用する前に、モデルがプレビューを表示し、チャットであなたの承認を得る必要があります。
auto	モデルはプレビューを確認した後、トークンを自動的に使用できます。
refuse	確認プロンプトを表示できないクライアントからの書き込みは拒否されます。認識されない値はrefuseとして扱われます。

BANDメンバーは、BANDから返される投稿、コメント、名前、チャットメッセージを書き込みます。これらのテキストは信頼できないデータとして扱われ、書き込みを許可することはできません。

ツール

読み取りツールでは view: compact | full を指定します（デフォルトは compact）。compact では閲覧に必要な情報が表示されます。full では BAND が送信したすべてのフィールドが表示されます。時刻は ISO 8601 形式です。ページ分割されるツールは next_cursor を返します。これを cursor として渡してください。

ツール	機能
band_healthcheck	BAND セッションを確認します。ブラウザーセッションを読み取れるか、有効期限までの残り時間、BAND の API がセッションを受け入れるかどうかを確認します。
band_whats_new	すべてのバンドにおける新着フィード投稿、未読チャットメッセージ、ニュースの件数を返します。
band_list_bands	所属しているバンド（グループ）の一覧を、番号、名前、メンバー数とともに返します。
band_get_band	1つのバンドの詳細を返します。種類、公開／非公開、メンバー数、リーダー、リンク、チャットのオン／オフを確認できます。
band_list_members	バンドのメンバー一覧を、役割、オンライン状態、参加日とともに返します。名前による絞り込みもできます。
band_list_posts	バンドのフィード（投稿とお知らせ）を新しい順に読み込みます。ページ分割に対応しています。
band_get_post	1つの投稿を全文で読み込みます。デフォルトでコメントも含まれます。
band_list_comments	1つの投稿へのコメント一覧を読み込みます。ページ分割に対応しています。
band_list_notices	バンドのお知らせ（重要として固定された投稿）を一覧表示します。
band_search_posts	キーワードでバンドの投稿を検索します。
band_list_events	2つの日付の間にあるバンドのカレンダーイベントを一覧表示します（デフォルトでは今後60日間）。
band_get_event	1つのカレンダーイベントを読み込みます。
band_list_chats	バンドのチャットチャンネルを、未読件数と最新メッセージとともに一覧表示します。
band_get_chat	1つのチャットチャンネルについて、参加者、未読状態、最新メッセージを読み込みます（履歴は含まれません）。
band_create_post	バンドに新しい投稿を作成します（確認が必要です。まずプレビューし、その後投稿します）。
band_create_comment	バンドの投稿にコメントします（確認が必要です。まずプレビューし、その後コメントします）。

制限事項

• チャット履歴はありません。 BAND のウェブ API で公開されるのは各チャットチャンネルの最新メッセージのみのため、band_get_chat では過去のメッセージを読み取れません。
• 出欠回答には対応していません。 イベントへの回答（参加、欠席、未定）は対象外です。投稿やコメント、写真、アルバム、投票の編集・削除、およびチャットメッセージの送信も対象外です。書き込み可能なのは新しい投稿と新しいコメントのみです。
• 米国の API ホストのみです。 すべての呼び出しは、米国アカウントでウェブアプリが使用するホスト api-us.band.us に送信されます。

MCP を使わないシェルアクセス

skills/band-fpx/ は、fpx CLI を使ってシェルから同じデータを読み取る、単独で動作する読み取り専用スキルです。

開発

npm install
npm run build        # tsc → dist/, then esbuild → dist/bundle.js (the .mcpb entry)
npm test             # typecheck + vitest
npm run test:coverage

docs/BAND-API.md では、このサーバーの基盤となる API について説明しています。ホスト、セッションの初期化、リクエスト署名、使用するすべてのエンドポイントが記載されています。

ライセンス

MIT