BAND

ruby-band-mcp-server

Ruby で公式の mcp gem を使用して実装され、stdio 経由で提供される、BAND Open API 用の MCP サーバーです。

ツール

ツール	説明
ping	サーバーが稼働していること、および BAND_ACCESS_TOKEN が設定されているかを報告します（値そのものは返しません）。
list_bands	参加しているバンドの一覧と、ほかのツールで必要となる band_key を返します。
create_post	バンドにテキスト投稿を公開します。do_push が true の場合のみ、メンバーにプッシュ通知が送られます。
get_post	band_key と post_key を指定して投稿を取得します。たとえば、create_post が反映されたことを確認できます。
list_posts	バンドの最近の投稿を、更新日時の新しい順に、after カーソルを使ってページ分割して一覧表示します。
check_permissions	バンドでユーザーが持つ posting、commenting、contents_deletion の権限を報告します。
remove_post	band_key と post_key を指定して投稿を完全に削除します。取り消すことはできません。
list_comments	投稿のコメントを古い順（newest_first を指定した場合を除く）に、after を使ってページ分割して一覧表示します。
create_comment	投稿にコメントを追加します。BAND はコメントのキーを返さないため、list_comments で確認してください。
remove_comment	comment_key を指定してコメントを完全に削除します。取り消すことはできません。

一般的な流れは、list_bands でバンドを見つけ、create_post で投稿を公開し、返された post_key を指定して get_post を実行し、投稿を確認することです。create_post は読み取り専用ではないとマークされているため、Claude Desktop などの MCP クライアントは実行前に確認できます。

バンド内の既存の投稿を確認するには、list_posts を使用します。BAND がページサイズ（20 件）を決定します。結果の next_after が null でない場合は、それを after として渡すと次のページを取得できます。

投稿に関するやり取りを読むには、投稿の band_key と post_key を指定して list_comments を使用します。コメントは古い順に並びます。順序を逆にするには、newest_first を設定します。テスト時、BAND が選択したページサイズは 20 件でした。next_after は返されたとおりに after として渡してください。順序が記憶されるため、最初のページ以降では newest_first は不要です。

コメントを投稿するには、create_comment を使用します。BAND はキーを示さずにコメントを受け付けたことを確認するため、投稿が反映されたことを確認し、comment_key を取得するには、その後 list_comments を呼び出してください。

投稿を削除するには、remove_post を使用します。破壊的操作としてマークされているため、クライアントは実行前に確認できます。まず contents_deletion を指定して check_permissions を実行してください。BAND のドキュメントによると、この権限確認では投稿者かどうかはチェックされないため、他のユーザーの投稿を削除しようとしても失敗する場合があります。remove_comment も同様に、list_comments から取得した comment_key を指定して使用します。BAND のドキュメントには、このアプリを通じて作成されたコメントのみ削除できるとも記載されています。

要件

Ruby 4.0 以降。

インストール

gem install band-mcp-server

これにより、PATH 上に band-mcp-server 実行ファイルが配置されます。インストールせずに実行する場合は、RubyGems がその場で取得して実行できます（gem と実行ファイルの名前は同じですが、gem exec では gem 名を明示する必要があります）。

gem exec -g band-mcp-server band-mcp-server

Docker

Ruby 4.0 のインストールを管理したくない場合は、各リリースのマルチアーキテクチャ（amd64 および arm64）イメージが ghcr.io/ktgeek/band-mcp-server に公開されています。このサーバーは stdio 経由で MCP を使用するため、-i を付けて実行し、トークンは環境変数経由で渡してください（イメージには設定ファイルがありません）。

export BAND_ACCESS_TOKEN=your-token
docker run -i --rm -e BAND_ACCESS_TOKEN ghcr.io/ktgeek/band-mcp-server

タグはリリースバージョン（たとえば 1.0.0）と latest です。Claude Code に登録するには、次のようにします。

claude mcp add band -e BAND_ACCESS_TOKEN=your-token -- \
  docker run -i --rm -e BAND_ACCESS_TOKEN ghcr.io/ktgeek/band-mcp-server

BAND アクセストークンの取得

BAND developer siteでアプリを登録し、そのアプリのアクセストークンを取得します。詳細はAPI guideをご覧ください。サーバーはトークンを受け取り、Authorization: BearerヘッダーとしてBANDに送信するだけです。サーバー自体はOAuthフローを実行しません。

トークンの設定

トークンを~/.config/band-mcp-server/config（または設定している場合は$XDG_CONFIG_HOME/band-mcp-server/config）に記述します。

mkdir -p ~/.config/band-mcp-server
echo 'BAND_ACCESS_TOKEN=your-token' > ~/.config/band-mcp-server/config
chmod 600 ~/.config/band-mcp-server/config

環境変数にすでに値が設定されている場合（たとえば、MCP クライアントのenv設定経由の場合）は、ファイルの値より優先されます。

実行

Claude Codeに登録します。

claude mcp add band -- band-mcp-server

サーバーはstdio経由でMCPを使用するため、通常は手動で実行するのではなく、クライアントによって起動されます。

Claude Desktop

Claude Desktopは最小限の環境でサーバーを起動するため、chrubyなどのバージョンマネージャーは有効にならず、インストール済みの実行ファイルにある#!/usr/bin/env rubyは誤ったRuby（システムにある場合はシステムRuby）を見つけてしまいます。chrubyを使っている場合は、chruby-exec経由でサーバーを起動してください。RubyとそのGEM_HOMEが選択されます。

chruby-execはログインシェル（$SHELL -l -c）でコマンドを実行するため、次の2つの条件を満たす必要があります。chrubyが、非対話型ログインシェルによって読み込まれる起動ファイル（zshの場合は~/.zprofileまたは~/.zshenv。~/.zshrcだけでは不可）で読み込まれていること。また、それらの起動ファイルが標準出力に何も出力しないこと。出力があると、プロトコルストリームの前に表示され、Desktopがハンドシェイクを解析できなくなります。

1. which chruby-execでchruby-execのインストール先を確認します。パスはchrubyのインストール方法によって異なり、DesktopのPATHは最小限のため、絶対パスで指定する必要があります。

2. Settings → Developer → Edit Configを開き（macOSでは~/Library/Application Support/Claude/claude_desktop_config.json）、mcpServersにbandエントリーを追加します。

   {
     "mcpServers": {
       "band": {
         "command": "/path/to/chruby-exec",
         "args": ["ruby-4", "--", "band-mcp-server"]
       }
     }
   }
   

   chrubyは、インストール済みのRubyの名前とruby-4を照合するため、4.xのRubyが選択されます。特定のバージョンに固定するには、ruby-4.0.5のように、より完全な名前を使います。同じRubyでgem install band-mcp-serverを実行してください。

   トークンは上記の設定ファイルに記述します。絶対パスから読み込まれるため、作業ディレクトリは関係ありません。代わりにenvマップでBAND_ACCESS_TOKENを設定することもできます。この場合も設定ファイルの値より優先されますが、シークレットがDesktopの設定ファイルに保存されます。

   chrubyを使わない場合は、インストール済みの実行ファイルの絶対パス（which band-mcp-server）をcommandに指定します。そのRubyがDesktopの最小限のPATHで最初に見つかるrubyではない場合は、代わりにRuby 4.0以降の絶対パスをcommandに指定し、実行ファイルをargsに設定して、インストール済みのgemが格納されているディレクトリをGEM_HOMEに設定します（gem env gemdirで確認できます）。

   {
     "mcpServers": {
       "band": {
         "command": "/path/to/ruby",
         "args": ["/path/to/band-mcp-server"],
         "env": { "GEM_HOME": "/path/to/gem/dir" }
       }
     }
   }
   

   Dockerを使う場合は、上記の設定は不要です。Desktopにはdockerの絶対パス（which docker）だけを指定し、トークンはenvマップに設定します。この場合、シークレットはDesktopの設定ファイルに保存されます。

   {
     "mcpServers": {
       "band": {
         "command": "/path/to/docker",
         "args": ["run", "-i", "--rm", "-e", "BAND_ACCESS_TOKEN", "ghcr.io/ktgeek/band-mcp-server"],
         "env": { "BAND_ACCESS_TOKEN": "your-token" }
       }
     }
   }
   

   シークレットをそのファイルに保存しないようにするには、自分だけが読み取れるファイルにBAND_ACCESS_TOKEN=your-tokenと記述し、envマップと"-e", "BAND_ACCESS_TOKEN"のペアを削除して、イメージ名の前に"--env-file", "/path/to/that/file"をargsに追加します。

3. Claude Desktopを完全に終了（Cmd-Q）してから、再度開きます。新しいチャットのツールメニューにbandツールが表示されます。 次に Claude に ping を実行させます。トークンを表示せずに設定されているかどうかを報告します。続けて「自分はどのバンドに所属していますか？」と尋ね、接続を確認します。ツールを常に許可するように設定していない限り、Desktop はツールの実行前に確認を求めます。 create_post と create_comment では、確認を有効にしておいてください。これらはバンドの全メンバーに公開されます。承認する前に、バンドとリクエストの文面を確認してください。create_post では、リクエストで do_push を設定した場合にのみ、メンバーにプッシュ通知が送信されます。remove_post と remove_comment でも、確認を有効にしておいてください。削除した内容は全メンバーに対して消去され、復元できません。承認する前にキーを確認してください。

Desktop 以外で起動コマンドを確認するには、最小限の環境変数で実行します。JSON の initialize 応答が返れば、その Ruby と gem でサーバーが起動しています。ただし、トークンは確認されません。トークンの確認には ping を使います。

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' |
  env -i HOME="$HOME" PATH=/usr/bin:/bin "$(which chruby-exec)" ruby-4 -- band-mcp-server

ツールが表示されない場合は、~/Library/Logs/Claude/mcp-server-band.log を確認してください。

ログまたはツール結果の症状	原因
spawn … ENOENT	command が、既存の chruby-exec（または Ruby）への絶対パスではありません。
chruby: unknown Ruby: …	args の名前に一致する Ruby がインストールされていません。chruby の出力と比較してください。
Could not find dotenv-…, mcp-…（gem が見つからない）	gem install が別の Ruby で実行されました。args で指定した Ruby で実行してください。
requires Ruby version >= 4.0	選択した Ruby は 4.0 より古いです。args（または command）を 4.x の Ruby に設定してください。
BAND_ACCESS_TOKEN is not set	トークンを含む設定ファイルがなく、env マップにも BAND_ACCESS_TOKEN がありません。
command not found: chruby	chruby は ~/.zshrc でしか読み込まれていません。~/.zprofile または ~/.zshenv で読み込んでください。
Desktop がサーバーの出力を解析できない	シェルの起動ファイルが標準出力に書き込んでいます。chruby-exec はログインシェルを実行します。
BAND API error 10401	BAND の「Unauthorized」コードです。トークンがない、無効、または期限切れです。

開発

チェックアウトした作業ツリーでは、インストール済みの gem ではなく Bundler を使います。チェックアウトのルートにある .env はユーザー設定ファイルより優先されます。また、band-mcp-server の代わりに bin/band-mcp-server（Bundler を自身でセットアップします）を使います。

chruby ruby-4.0.5   # or any manager that reads .ruby-version
bundle install
cp .env.example .env    # then set BAND_ACCESS_TOKEN
claude mcp add band -- /path/to/ruby-band-mcp-server/bin/band-mcp-server

bundle exec rake    # rubocop, rbs drift check, steep, rspec
bundle exec rake -T # every task, including audit

lib/ は rbs-inline の注釈で型付けされ、Steep でチェックされています。注釈を変更した後は、bundle exec rake rbs:generate で sig/generated/ を再生成してください。規約とアーキテクチャについては AGENTS.md を参照してください。

main は保護されています。変更は、CI がすべて成功したプルリクエストを通じて取り込まれます。

ライセンス

GPL-3.0。LICENSE を参照してください。