免责声明： 这是一个独立的、由社区构建的项目， 与 KegLand 或 RAPT.io 均无关联，亦未经其认可或支持。 RAPT、RaptPill 和 KegLand 均为其各自所有者的商标， 在此仅用于描述兼容性。 本软件按“原样”提供，不附带任何形式的担保——完整条款见 LICENSE，其中包含专门针对本项目使用不受支持的 第三方 API 的额外通俗语言免责声明。

RAPT.io MCP Server

一个用于通过 RAPT.io API 监控和控制 KegLand RAPT 设备（Fermentation Chamber 和 RaptPill 比重计）的 MCP（Model Context Protocol，模型上下文协议）服务器。

⚠️ 默认只读。 RAPT.io API 对大多数变更操作而言既不受支持， 也没有文档说明（参见下文 安全与 API 使用说明）。 本服务器会拒绝所有发送到 RAPT.io API 的 POST 请求，除非操作者 明确通过 RAPTIO_MCP_READ_ONLY=false 选择启用。

功能

Fermentation Chamber（发酵室）

• 列出所有发酵室

• 获取状态（温度、加热/制冷、PID、运行时长）

• 获取遥测历史数据

• （当 RAPTIO_MCP_READ_ONLY=false 时） 设置目标温度、启用/禁用 PID、配置 PID 参数

RaptPill（比重计）

• 列出所有 RaptPill

• 获取状态（比重、温度、电池电量）

• 获取遥测历史数据

通用

• 列出所有已绑定设备

• 管理/查看发酵档案

此前可用的一些控制类工具（加热/制冷/风扇/灯光开关、迟滞、压缩机/模式切换延迟）已被移除， 等待对底层 API 端点的验证。请参见下文 已移除的工具。

Related MCP server: Intervals.icu MCP

安装

环境要求

• Python 3.11+

• uv（推荐）或 pip

使用 uv

uv sync --frozen

使用 pip

pip install -e .

身份验证

本服务器使用您的 RAPT.io 用户名和 API Secret（而非您的账户密码）向 RAPT.io API 进行身份验证。

1. 登录 RAPT Portal。

2. 进入 My Account → API Secrets（https://app.rapt.io/account/apisecrets）。

3. 点击 Add API Secret 并立即记录该值——它会在服务端进行哈希处理，之后将无法再次查看。

请勿将您的真实账户密码用作 RAPT_API_SECRET。API Secret 是一种独立的、可单独撤销的凭据——即使泄露，您也可以在门户网站中重新轮换它，而不会影响真实的账户登录凭据。

配置

设置以下环境变量：

使用

直接运行（Streamable HTTP）

RAPT_USERNAME="you@example.com" \
RAPT_API_SECRET="your-api-secret" \
RAPTIO_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  uv run raptio-mcp

服务器监听于 http://<RAPTIO_MCP_HOST>:<RAPTIO_MCP_PORT>/mcp（Streamable HTTP transport，无状态，JSON 响应）。所有发送到 /mcp 的请求都需要上述 Bearer Token。/healthz 无需认证，用于容器编排器的存活/就绪探针。

连接 MCP 客户端

配置您的 MCP 客户端使用 Streamable HTTP transport，例如：

claude mcp add --transport http raptio http://localhost:8000/mcp \
  --header "Authorization: Bearer <your RAPTIO_MCP_AUTH_TOKEN>"

本服务器更早的版本使用 stdio transport（供 Claude Desktop/Claude Code 通过本地子进程使用）。自 0.2.0 起，服务器仅通过 Streamable HTTP 运行，并要求上述 Bearer Token——进程所有权不再构成隐式信任边界，因此必须强制认证。

可用工具

当 RAPTIO_MCP_READ_ONLY=true（默认）时，这三个变更类工具仍会列出（因此其 schema 依旧可发现），但每次调用都会返回明确的错误，而不会真正到达 RAPT.io API。

已移除的工具

以下工具存在于早期版本中，但已被移除并等待验证：

• set_fermentation_chamber_heating_enabled

• set_fermentation_chamber_cooling_enabled

• set_fermentation_chamber_fan_enabled

• set_fermentation_chamber_light_enabled

• set_fermentation_chamber_cooling_hysteresis

• set_fermentation_chamber_heating_hysteresis

• set_fermentation_chamber_compressor_delay

• set_fermentation_chamber_mode_switch_delay

它们此前都依赖 POST /api/FermentationChambers/UpdateFermentationChamber，该端点并未出现在 RAPT.io 的已发布 API 规范（https://api.rapt.io/swagger/v1/swagger.json）中，也没有文档化的并发行为说明。只有在通过活跃账户确认该端点存在且安全之后，这些工具才会被恢复。（set_fermentation_chamber_light_enabled 此前还发送了错误的枚举值——On/Off/Auto，而不是正确的 AlwaysOn/AlwaysOff/Automatic——在恢复前也需要一并修复。）

安全与 API 使用说明

RAPT.io 公共 API 被 KegLand 明确描述为不受支持：

“访问 API 不受支持。这意味着您在使用 API 时遇到任何问题都无法从 KegLand 获得帮助……如果您因滥用 API 而损坏设备，设备的保修将失效……API（端点、参数、响应模型等）随时可能变更，恕不另行通知。” — https://docs.rapt.io/integrations/api-secrets

鉴于以上原因，服务器默认采取保守策略：

• 默认只读（RAPTIO_MCP_READ_ONLY=true）——除非显式启用，否则不会发送任何可能改变设备状态的请求。

• 仅使用官方文档化的端点进行变更——SetTargetTemperature、SetPIDEnabled、SetPID——这些都已确认出现在 RAPT.io 自己的已发布 Swagger 规范中。

• 未使用未经文档化的端点——见 已移除的工具。

• HTTP transport 强制要求认证（RAPTIO_MCP_AUTH_TOKEN），因为 Streamable HTTP 失去了先前 stdio 子进程模型免费提供的隐式信任边界，因此认证是强制性要求。

• 所有变更类工具的调用都会写入审计日志（工具名称、参数、结果）。

如果您选择设置 RAPTIO_MCP_READ_ONLY=false，即表示您主动同意向实体酿造/发酵设备发送命令，而这依赖于 KegLand 可能随时更改或限制的 API；由此造成的任何损坏或账户限制，将按照上文 KegLand 的条款并由您自行负责。

身份验证流程详情

在内部，服务器会使用你的 RAPT_USERNAME 和 RAPT_API_SECRET，通过 OAuth2 Resource Owner Password Credentials 授权流程，向 https://id.rapt.io/connect/token 换取一个短期有效的 bearer token，遵循 RAPT.io 的文档化流程。令牌会缓存在内存中，并在过期前约 30 秒自动刷新。

许可证

MIT