RAPT.io MCP Server

Disclaimer: This is an independent, community-built project and isnot affiliated with, endorsed by, or supported by KegLand orRAPT.io. RAPT, RaptPill, and KegLand are trademarks of theirrespective owners, referenced here solely to describe compatibility.This software is provided as is, with no warranty of any kind — seeLICENSE for full terms, including an additionalplain-language disclaimer specific to this project's use of anunsupported third-party API.

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

⚠️ Read-only by default. The RAPT.io API is unsupported andundocumented for most mutating operations (seeSecurity & API usage notes below). Thisserver refuses all POST requests to the RAPT.io API unless anoperator 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/lighttoggles, hysteresis, compressor/mode-switch delay) have been removedpending verification of the underlying API endpoint. SeeRemoved tools below.

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 usernameand an API Secret (not your account password).

Log in to the RAPT Portal.
Navigate to My Account → API Secrets(https://app.rapt.io/account/apisecrets).
Click Add API Secret and record the value immediately — it ishashed server-side and cannot be retrieved again later.

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

Configuration

Set the following environment variables:

Variable	Required	Default	Description
`RAPT_USERNAME`	yes	—	RAPT.io account email
`RAPT_API_SECRET`	yes	—	API Secret generated at app.rapt.io/account/apisecrets
`RAPTIO_MCP_AUTH_TOKEN`	yes	—	Shared-secret bearer token that MCP clients must send as `Authorization: Bearer <token>`
`RAPTIO_MCP_READ_ONLY`	no	`true`	When `true` (default), all mutating (`set_*`) tool calls are refused before reaching the RAPT.io API. Set to `false` to allow the documented mutating endpoints (see Security & API usage notes)
`RAPTIO_MCP_ALLOWED_HOSTS`	recommended	(unset — validation disabled)	Comma-separated list of allowed `Host` header values (DNS-rebinding protection)
`RAPTIO_MCP_ALLOWED_ORIGINS`	recommended	(unset — validation disabled)	Comma-separated list of allowed `Origin` header values
`RAPTIO_MCP_HOST`	no	`0.0.0.0`	Bind address
`RAPTIO_MCP_PORT`	no	`8000`	Bind port
`RAPTIO_MCP_LOG_LEVEL`	no	`INFO`	Python logging level

Usage

Run directly (Streamable HTTP)

RAPT_USERNAME="[email protected]" \
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 andintended 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 localsubprocess use with Claude Desktop/Claude Code). As of 0.2.0 theserver runs exclusively over Streamable HTTP, which requires the bearertoken above — there is no longer an implicit trust boundary fromprocess ownership, so authentication is mandatory.

Available Tools

Tool	Description	Mode
`get_bonded_devices`	List all bonded devices	read-only
`get_bonded_device`	Get a single device	read-only
`get_bonded_device_telemetry`	Get device telemetry	read-only
`get_fermentation_chambers`	List all fermentation chambers	read-only
`get_fermentation_chamber`	Get chamber status	read-only
`get_fermentation_chamber_telemetry`	Get chamber temperature history	read-only
`set_fermentation_chamber_temperature`	Set target temperature	mutating — requires `RAPTIO_MCP_READ_ONLY=false`
`set_fermentation_chamber_pid_enabled`	Enable/disable PID control	mutating — requires `RAPTIO_MCP_READ_ONLY=false`
`set_fermentation_chamber_pid`	Configure PID parameters	mutating — requires `RAPTIO_MCP_READ_ONLY=false`
`get_hydrometers`	List all RaptPills	read-only
`get_hydrometer`	Get RaptPill status	read-only
`get_hydrometer_telemetry`	Get gravity/temperature history	read-only
`get_profiles`	List all fermentation profiles	read-only
`get_profile`	Get profile details	read-only
`get_profile_types`	List available profile types	read-only

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

Removed tools

The following tools existed in earlier versions but have been removedpending 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 APIspecification (https://api.rapt.io/swagger/v1/swagger.json) and has nodocumented concurrency behavior. They will be reinstated only after theendpoint's existence and safety have been confirmed against a liveaccount. (set_fermentation_chamber_light_enabled also previously sentincorrect enum values — On/Off/Auto instead of the correctAlwaysOn/AlwaysOff/Automatic — and will need that fix appliedbefore reinstatement too.)

Security & API usage notes

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

"Access to the Api is unsupported. This means you will not getassistance from KegLand with regards to any issues you may encounterwhile using the Api... if you destroy a device through misuse of theApi, 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 requestthat could change device state is sent unless explicitly enabled.
Only officially-documented endpoints are used for mutations —SetTargetTemperature, SetPIDEnabled, SetPID — all confirmedpresent 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 theprevious 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 intosending commands to physical brewing/fermentation hardware over anAPI that KegLand may change or restrict without notice, and any damageor account restriction resulting from that use is your responsibilityper KegLand's own terms above.

Authentication flow details

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

License

MIT

RAPT.io MCP Server