band-mcp

BAND MCP

一个 Model Context Protocol 服务，可将 Claude 连接到 BAND。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 包。其可选设置（时区、写入确认模式、确认提示词、调试日志、Bridge 端口）用于设置配置中的环境变量；留空即可使用默认值。

登录方式

BAND 的 Web API 需要两项只有你的浏览器才有的信息：band.us 会话 Cookie，以及 BAND 只会提供给网页的每会话签名密钥。从其他地方获取时，签名密钥会返回空值。此服务使用 fetchproxy Bridge（ContextMint Bridge）来：

1. 从你已登录的标签页读取 band.us 会话 Cookie（会话令牌和五个配套 Cookie，列于 docs/BAND-API.md）；
2. 通过该标签页获取签名密钥。

随后，每次 API 调用都会直接从 Node 发送到 https://api-us.band.us，并使用请求 URL 的 HMAC 进行签名。Cookie 和密钥只保存在内存中，不会出现在错误、结果或日志中。写入你的主目录的唯一内容是 Bridge 的配对身份信息。此服务不会获取或存储你的密码。

band.us 会话会持续几天。会话距离过期不到 10 分钟时，服务会从你的标签页重新读取会话。如果 BAND 返回“未授权”，服务也会重新读取一次，并对每次调用重试一次。服务不会自行刷新会话，因为在浏览器外轮换令牌可能会让浏览器退出登录。如果调用开始失败，请打开或重新加载 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。然后运行 fpx trust clear band-mcp（来自 @fetchproxy/cli），重启服务并重新配对。

配置

环境变量	默认值	用途
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 elicitation 的客户端会显示真实的确认提示，其中会注明社群并显示文本。
• 其他客户端（claude.ai、Claude Desktop）在首次调用时不会进行任何更改。调用会返回预览和一个单次使用、短时有效的 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 中的新动态帖子、未读聊天消息和新闻数量。
band_list_bands	列出你加入的 BAND（群组），包括编号、名称和成员数。
band_get_band	获取一个 BAND 的详情：类型、公开或私密、成员数、负责人、链接、聊天是否开启。
band_list_members	列出一个 BAND 的成员及其角色、在线状态和加入日期；可选按姓名筛选。
band_list_posts	读取一个 BAND 的动态，包括帖子和公告，按最新优先排序，支持分页。
band_get_post	完整读取一篇帖子，默认包括评论。
band_list_comments	列出一篇帖子的评论，支持分页。
band_list_notices	列出一个 BAND 的通知（置顶为重要的帖子）。
band_search_posts	按关键词搜索一个 BAND 的帖子。
band_list_events	列出两个日期之间的一个 BAND 日历活动（默认未来 60 天）。
band_get_event	读取一项日历活动。
band_list_chats	列出一个 BAND 的聊天频道，包括未读数量和最新消息。
band_get_chat	读取一个聊天频道的信息：参与者、未读状态和最新消息（不含历史记录）。
band_create_post	在一个 BAND 中发布新帖子（需确认：先预览，再发布）。
band_create_comment	评论一个 BAND 帖子（需确认：先预览，再评论）。

限制

• 没有聊天历史记录。 BAND 的 Web API 只提供每个聊天频道的最新消息，因此 band_get_chat 无法读取更早的消息。
• 不支持回复活动邀请。 不在此工具范围内的操作包括回复活动邀请（参加、拒绝、待定）、编辑或删除帖子和评论、管理照片、相册和投票，以及发送聊天消息。唯一支持的写入操作是发布新帖子和新评论。
• 仅使用美国 API 主机。 所有调用均发送至 api-us.band.us，这是 Web 应用为美国账户使用的主机。

不使用 MCP 的 Shell 访问

skills/band-fpx/ 是一个独立的只读技能，可通过 fpx CLI 在 Shell 中读取相同数据。

开发

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