BAND

ruby-band-mcp-server

一个面向 BAND Open API 的 MCP 服务，使用官方 mcp gem 以 Ruby 编写，并通过 stdio 提供服务。

工具

工具	功能说明
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 传回即可获取下一页。

若要查看动态下的讨论，请使用 list_comments，并传入动态的 band_key 和 post_key。评论默认按时间从旧到新排列；将 newest_first 设为相反值即可反转顺序。测试时，BAND 选择了每页 20 条。请将 next_after 按原样作为 after 传回：它会记住排序顺序，因此第一页之后的页面无需设置 newest_first。

若要参与讨论，请使用 create_comment。BAND 会确认评论已发布，但不会说明其键是什么，因此请在之后调用 list_comments，确认评论已发布并获取其 comment_key。

若要删除动态，请使用 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 安装环境，可以从 ghcr.io/ktgeek/band-mcp-server 获取每个版本的多架构镜像（amd64 和 arm64）。该服务通过 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 开发者网站上注册应用并获取访问令牌；API 指南介绍了具体细节。服务只会使用该令牌，并将其作为 Authorization: Bearer 标头发送给 BAND。服务本身不会运行任何 OAuth 流程。

配置令牌

将令牌放入 ~/.config/band-mcp-server/config（如果设置了 $XDG_CONFIG_HOME，则放入 $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（$SHELL -l -c）中运行命令，因此必须满足两项条件。chruby 必须由非交互式登录 shell 会读取的启动文件加载（对于 zsh，应使用 ~/.zprofile 或 ~/.zshenv，而不能只放在 ~/.zshrc 中）。此外，这些启动文件不得向 stdout 输出任何内容，否则内容会出现在协议流前面，Desktop 将无法解析握手。

1. 使用 which chruby-exec 查找 chruby-exec 的安装位置。位置取决于 chruby 的安装方式；由于 Desktop 的 PATH 很精简，此处必须使用绝对路径。

2. 打开“设置” →“开发者”→“编辑配置”（在 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-4 与已安装的 Ruby 版本匹配，因此会选择 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_HOME 设置为存放已安装 gem 的目录（运行 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" 这一对参数，并在 args 中的镜像名称之前添加 "--env-file", "/path/to/that/file"。

3. 完全退出 Claude Desktop（Cmd-Q）并重新打开。新聊天的工具菜单中会显示 band 工具。 然后让 Claude 运行 ping。它会报告令牌是否已设置，但不会显示令牌；接着询问“我加入了哪些乐队？”，以确认连接正常。除非你已将某个工具设为始终允许，否则桌面应用会在运行工具前征求确认。 对 create_post 和 create_comment 保持确认提示开启：它们会向乐队的所有成员发布内容。批准前，请查看乐队和请求中的措辞。对于 create_post，只有请求设置了 do_push，才会向成员发送推送通知。对 remove_post 和 remove_comment 也保持确认提示开启：删除的内容会对所有成员永久消失，且无法恢复，因此批准前请检查键值。

若要在桌面应用之外检查启动命令，请在干净的环境中运行该命令。JSON initialize 响应表示服务已在该 Ruby 版本下使用其 gems 启动；它不会检查令牌，检查令牌需运行 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: …	没有已安装的 Ruby 与 args 中的名称匹配；请与 chruby 的输出进行比较。
Could not find dotenv-…, mcp-…（缺少 gems）	gem install 是在另一个 Ruby 版本下运行的；请在 args 指定的版本下运行。
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 中加载。
桌面应用无法解析服务的输出	Shell 启动文件向 stdout 输出内容；chruby-exec 会运行登录 Shell。
BAND API error 10401	BAND 的“未授权”错误代码：令牌缺失、无效或已过期。

开发

从检出目录开始，请使用 Bundler，而非已安装的 gem。检出目录根目录中的 .env 优先于用户配置文件；bin/band-mcp-server（会自行设置 Bundler）取代 band-mcp-server：

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。