고지: 이 프로젝트는 독립적으로 만들어진 커뮤니티 프로젝트이며, KegLand나 RAPT.io와 함께 배포되어 있지 않고, 이들의 보증·지원도 받지 않습니다. RAPT, RaptPill, KegLand는 각각 해당 소유자의 상표로 호환성 설명을 전용으로 언급됩니다. 이 소프트웨어는 보증이 전혀 없는 그대로(as is) 제공됩니다. — 전체 약관과 지원되지 않는 제3자 API에 대한 추가의 일반 용어 면책 고지에 대한 상세 내용은 LICENSE를 참조하세요.

RAPT.io MCP Server

RAPT.io API를 통해 KegLand RAPT 기기(발효 챔버 및 RaptPill 비중계)를 모니터링·제어하기 위한 MCP(Model Context Protocol) 서버입니다.

⚠️ 기본적으로 읽기 전용입니다. RAPT.io API는 대부분의 상태 변경 작업에 대해 지원되지 않고 문서화되지도 않았습니다(아래 보안 및 API 사용 시 유의사항 참조). 이 서버는 운영자가 RAPTIO_MCP_READ_ONLY=false 로 명시적으로 선택하지 않는 한, RAPT.io API 에 대한 모든 POST 요청을 거부합니다.

Features

• 발효 챔버

  • 모든 발효 챔버 목록 가져오기

  • 상태 가져오기(온도, 가열/냉각, PID, 가동 시간)

  • 원격측정(텔레메트리) 히스토리 가져오기

  • (when RAPTIO_MCP_READ_ONLY=false) 목표 온도 설정, PID 활성화/비활성화, PID 매개변수 구성

• RaptPill (Hydrometer)

  • 모든 RaptPill 목록 가져오기

  • 상태 가져오기(비중, 온도, 배터리 잔량)

  • 원격측정(텔레메트리) 히스토리 가져오기

• 일반 기능

  • 모든 연결 기기 나열

  • 발효 프로파일 관리/조회

다음에서 존재했던 여러 제어 도구(가열/냉각/팬/조명 토글, 히스테리시스, 압축기/모드 전환 지연)는 기본 API 엔드포인트 검증을 위해 제거되었습니다. 아래 제거된 도구 참고.

Related MCP server: RAPT.io MCP Server

설치

요구 사항

• Python 3.11+

• uv(권장) 또는 pip

uv를 사용한 설치

uv sync --frozen

pip을 사용한 설치

pip install -e .

인증

이 서버는 RAPT.io API에 RAPT.io 사용자 이름과 API 시크릿(계정 비밀번호가 아님)을 이용하여 인증합니다.

1. RAPT 포털에 로그인합니다.

2. My Account → API Secrets(https://app.rapt.io/account/apisecrets)로 이동합니다.

3. Add API Secret을 클릭하고 값을 즉시 기록해 두세요. — 서버는 해시 처리된 값을 저장하므로 나중에 다시 조회할 수 없습니다.

RAPT_API_SECRET에는 실제 계정 비밀번호를 사용하지 마세요. API 시크릿은 별도의, 독립적으로 취소(회전)할 수 있는 자격 증명입니다. — 이 값이 유출되면 실제 계정 로그인 정보에는 손대지 않고 포털에서 회전시킬 수 있습니다.

구성

다음 환경 변수를 설정하세요:

사용법

직접 실행(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 전송, 무상태·JSON 응답)에서 요청을 받습니다. /mcp의 모든 요청에는 위에 설명한 bearer 토큰이 필요합니다. /healthz는 인증 없이 접근할 수 있고, 오케스트레이터의 활성/준비 상태 프로브용으로 사용합니다.

MCP 클라이언트 연결

Streamable HTTP 클라이언트를 사용하도록 MCP 클라이언트를 설정하세요.

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

이 서버의 이전 버전은 stdio 전송(Claude Desktop/Claude Code 로컬 하위 프로세스용)을 사용했습니다. 0.2.0부터는 서버가 오직 Streamable HTTP에서만 실행되며, 위의 bearer 토큰이 필요합니다. 프로세스 소유로 인한 암묵적인 신뢰 경계가 더 이상 존재하지 않으므로 인증은 필수입니다.

사용 가능한 도구

RAPTIO_MCP_READ_ONLY=true(기본값)인 상태에서도 이 세 상태변경 도구는 목록에 포함되어 스키마(스키마)를 계속 탐색할 수 있지만, 모든 호출은 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)에 나타나 있지 않으며, 동시성 (concurrency) 동작과 관련한 문서화도 없습니다. 실제 계정에서 해당 엔드포인트의 존재와 안전함을 확인하기 전에는 다시 포함시킬 예정이 없습니다. (set_fermentation_chamber_light_enabled는 또한 이전에 잘못된 enum 값 On/Off/Auto를 보냈고 — 올바른 값은 AlwaysOn/AlwaysOff/Automatic입니다 — 이 오류도 함께 수정해야 제도 포함됩니다.)

보안 & API 사용 시 유의사항

Rapt.io 공용 API는 KegLand가 명시적으로 **지원하지 않음(unSupported)**으로 설명합니다.

"API 접근은 지원되지 않습니다. 즉, API를 사용하면서 겪는 어떤 문제에 대해서도 KegLand로부터 도움을 받을 수 없습니다... API를 잘못 사용하여 기기를 파괴하면 보증이 무효화됩니다... API(엔드포인트, 매개변수, 응답 모델 등)는 예고 없이 변경될 수 있습니다." — https://docs.rapt.io/integrations/api-secrets

이것을 고려하여 서버는 기본적으로 보수적인 입장을 취합니다.

• 기본적으로 읽기 전용(RAPTIO_MCP_READ_ONLY=true) — 명시적으로 허용되지 않음 이상, 기기의 상태를 바꿀 수 있는 요청을 전혀 보내지 않습니다.

• 상태 변경은 공식적으로 문서화된 엔드포인트만 사용합니다 — SetTargetTemperature, SetPIDEnabled, SetPID — 모두 RAPT.io가 직접 공표한 Swagger 스펙에 존재하는 것이 확인된 항목입니다.

• 문서화되지 않은 엔드포인트는 사용하지 않습니다. — 위의 제거된 도구 참고.

• 인증을 강제합니다 — HTTP 전송(RAPTIO_MCP_AUTH_TOKEN)에서는 반드시 인증해야 합니다. Streamable HTTP는 기존 stdio 하위프로세스 모델 암시적으로 부여하던 신뢰 경계를 제거합니다.

• 모든 상태 변경 도구 호출은 서버의 구조화된 로그(audit)로 기록합니다.(도구 이름, 인자, 결과를 포함)

RAPTIO_MCP_READ_ONLY=false로 설정하는 것은, 언제든 변경이나 제한될 수 있는 RPT.io API를 통해 실제의 양조/발효 하드웨어에 명령을 보내는 것을 선택하는 것입니다. 그에 따른 피해나 계정 제한이 발생하더라도 앞서의 Rapt.io 약속대로 이용자에게 책임이 있습니다.

인증 흐름 상세 내용설

내부적으로 서버는 RAPT.io가 문서화한 흐름에 따라 https://id.rapt.io/connect/token에 대해 OAuth2 Resource Owner Password Credentials grant를 사용해 사용자의 RAPT_USERNAME 및 RAPT_API_SECRET을 단기 유효한 bearer 토큰으로 교환합니다. 토큰은 메모리에 캐시되며 만료 약 30초 전에 자동으로 갱신됩니다.

라이선스

MIT