Disclaimer: This is an independent, community-built project and is not affiliated with, endorsed by, or supported by KegLand or RAPT.io. RAPT, RaptPill, and KegLand are trademarks of their respective owners, referenced here solely to describe compatibility. This software is provided as is, with no warranty of any kind — see LICENSE for full terms, including an additional plain-language disclaimer specific to this project's use of an unsupported third-party API.

RAPT.io MCP Server

An MCP (Model Context Protocol) server for monitoring and controlling KegLand RAPT devices — Fermentation Chambers and RaptPill hydrometers — via the RAPT.io API.

⚠️ Read-only by default. The RAPT.io API is unsupported and undocumented for most mutating operations (see Security & API usage notes below). This server refuses all POST requests to the RAPT.io API unless an operator explicitly opts in via RAPTIO_MCP_READ_ONLY=false.

Features

Fermentation Chamber

• List all fermentation chambers

• Get status (temperature, heating/cooling, PID, run times)

• Get telemetry history

• (when RAPTIO_MCP_READ_ONLY=false) Set target temperature, enable/disable PID, configure PID parameters

RaptPill (Hydrometer)

• List all RaptPills

• Get status (gravity, temperature, battery level)

• Get telemetry history

General

• List all bonded devices

• Manage/view fermentation profiles

Several previously-available control tools (heating/cooling/fan/light toggles, hysteresis, compressor/mode-switch delay) have been removed pending verification of the underlying API endpoint. See Removed tools below.

Related MCP server: RAPT.io MCP Server

Installation

Requirements

• Python 3.11+

• uv (recommended) or pip

With uv

uv sync --frozen

With pip

pip install -e .

Authentication

This server authenticates to the RAPT.io API using your RAPT.io username and an API Secret (not your account password).

1. Log in to the RAPT Portal.

2. Navigate to My Account → API Secrets (https://app.rapt.io/account/apisecrets).

3. Click Add API Secret and record the value immediately — it is hashed server-side and cannot be retrieved again later.

Do not use your actual account password for RAPT_API_SECRET. The API Secret is a separate, independently revocable credential — if it leaks, you can rotate it from the portal without touching your real account login.

Configuration

Set the following environment variables:

Usage

Run directly (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

The server listens on http://<RAPTIO_MCP_HOST>:<RAPTIO_MCP_PORT>/mcp (Streamable HTTP transport, stateless, JSON responses). All requests to /mcp require the bearer token above. /healthz is unauthenticated and intended for orchestrator liveness/readiness probes.

Connecting an MCP client

Configure your MCP client to use the Streamable HTTP transport, e.g.:

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

Earlier versions of this server used the stdio transport (for local subprocess use with Claude Desktop/Claude Code). As of 0.2.0 the server runs exclusively over Streamable HTTP, which requires the bearer token above — there is no longer an implicit trust boundary from process ownership, so authentication is mandatory.

Available Tools

While RAPTIO_MCP_READ_ONLY=true (default), the three mutating tools are still listed (so their schemas remain discoverable) but every call returns an explicit error instead of reaching the RAPT.io API.

Removed tools

The following tools existed in earlier versions but have been removed pending verification:

• 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

They all relied on POST /api/FermentationChambers/UpdateFermentationChamber, an endpoint that does not appear in RAPT.io's published API specification (https://api.rapt.io/swagger/v1/swagger.json) and has no documented concurrency behavior. They will be reinstated only after the endpoint's existence and safety have been confirmed against a live account. (set_fermentation_chamber_light_enabled also previously sent incorrect enum values — On/Off/Auto instead of the correct AlwaysOn/AlwaysOff/Automatic — and will need that fix applied before reinstatement too.)

Security & API usage notes

The RAPT.io public API is explicitly described by KegLand as unsupported:

"Access to the Api is unsupported. This means you will not get assistance from KegLand with regards to any issues you may encounter while using the Api... if you destroy a device through misuse of the Api, it will void your warranty... The Api (endpoints, parameters, response models etc.) is subject to change without notice." — https://docs.rapt.io/integrations/api-secrets

Given this, the server defaults to a conservative posture:

• Read-only by default (RAPTIO_MCP_READ_ONLY=true) — no request that could change device state is sent unless explicitly enabled.

• Only officially-documented endpoints are used for mutations — SetTargetTemperature, SetPIDEnabled, SetPID — all confirmed present in RAPT.io's own published Swagger spec.

• Undocumented endpoints are not used — see Removed tools.

• Authentication is mandatory on the HTTP transport (RAPTIO_MCP_AUTH_TOKEN), since Streamable HTTP removes the implicit trust boundary that the previous stdio-subprocess model provided for free.

• All mutating tool calls are audit-logged (tool name, arguments, outcome) to the server's structured logs.

If you choose to set RAPTIO_MCP_READ_ONLY=false, you are opting into sending commands to physical brewing/fermentation hardware over an API that KegLand may change or restrict without notice, and any damage or account restriction resulting from that use is your responsibility per KegLand's own terms above.

Authentication flow details

Internally, the server exchanges your RAPT_USERNAME and RAPT_API_SECRET for a short-lived bearer token via OAuth2 Resource Owner Password Credentials grant against https://id.rapt.io/connect/token, per RAPT.io's documented flow. Tokens are cached in memory and refreshed automatically ~30 seconds before expiry.

License

MIT