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.

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:

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="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

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 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