chrisdoc/hevy-mcp

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

Hevy MCP – Hevy 피트니스 앱을 위한 AI 친화적 브리지

개요 – hevy-mcp는 **Model Context Protocol (MCP)**을 구현하는 작은 오픈소스 서버입니다. Hevy 운동 추적 API(읽기 전용 및 쓰기 가능 엔드포인트)를 Claude, Codex, Cursor 또는 기타 MCP 호환 클라이언트가 호출할 수 있는 일련의 MCP 도구로 노출합니다.

중요성 – 개인 운동 데이터를 표준 도구 인터페이스로 변환함으로써, 이 서버는 대규모 언어 모델 어시스턴트가 훈련 기록을 추론하고, 자연어 질문에 답하고, 운동, 루틴, 맞춤 운동, 신체 측정 기록을 생성하거나 업데이트할 수 있게 합니다. 모든 작업은 사용자의 명시적 동의 하에 이루어집니다.

핵심 기능 (23개 도구)

카테고리	도구 예시	수행 가능 작업
훈련 분석	`get-training-summary`, `analyze-workout-progress` (안내 프롬프트)	몇 주간의 운동 및 신체 측정 요약, 누락 파악, 가장 빈번한 운동 표시.
운동	`get-workouts`, `get-workout`, `create-workout`, `update-workout`, `replace-workout-exercises`, `get-workout-events`	과거 세션 목록, 개별 운동 세부 정보 가져오기, 새 완료 운동 기록, 메타데이터 또는 운동 세트 편집.
루틴 및 폴더	`search-routines`, `get-routines`, `get-routine`, `create-routine`, `update-routine`, `create-routine-folder`, `get-routine-folder`	저장된 루틴 검색, 루틴 레이아웃 읽기, 재사용 가능한 새 루틴 생성 또는 폴더로 구성.
운동 카탈로그	`search-exercise-templates`, `get-exercise-template`, `create-exercise-template`, `get-exercise-history`	Hevy의 전체 운동 라이브러리 탐색, 맞춤 템플릿 추가, 특정 운동의 과거 수행 세트 검색.
신체 측정	`get-body-measurements`, `get-body-measurement`, `create-body-measurement`, `update-body-measurement`	체중, 체지방률 등 추적, 항목 추가 또는 수정.
진단	`feedback`	문제 발생 시 개인정보 안전한 짧은 보고서 전송.

모든 변경 도구는 MCP 확인으로 표시되어 있어 호환 클라이언트가 데이터 변경 작업 전에 사용자에게 확인을 요청합니다.

작동 방식

AI 어시스턴트 → MCP (스트리밍 HTTP 또는 stdio) → hevy-mcp 서버 → Hevy API

호스팅 모드 – Cloudflare Worker가 https://mcp.hevy-mcp.dev/mcp에서 서버를 실행합니다. 클라이언트는 고정 Authorization: Bearer <Hevy-API키> 헤더를 전송합니다. Worker는 키를 검증하고 15분간 캐시한 후 Hevy로 전달합니다.
로컬 모드 – npm 패키지(또는 Docker 이미지)를 자신의 머신에서 실행합니다. 서버는 HEVY_API_KEY 환경 변수에서 API 키를 읽고 stdio를 통해 클라이언트와 통신합니다.
OAuth 계층 – 호스팅된 Worker는 선택적 OAuth 2.1 흐름(Claude.ai 사용자 지정 커넥터에서 사용)도 제공하여 키를 암호화된 상태로 권한 부여에 저장하므로, 정적 헤더를 설정할 수 없는 클라이언트도 인증할 수 있습니다.

시작하기 (가장 빠른 방법)

Hevy API 키 얻기 – Hevy PRO 구독 필요 (설정 → 개발자 → API 키).
연결 – 공개 엔드포인트 https://mcp.hevy-mcp.dev/mcp 사용.
- Codex: 환경에 HEVY_API_KEY 설정 후 codex mcp add hevy --url https://mcp.hevy-mcp.dev/mcp --bearer-token-env-var HEVY_API_KEY로 서버 추가.
- 기타 클라이언트: 동일한 URL과 고정 Authorization: Bearer <키> 헤더 제공.
질문하기 – 예: "지난 4주간의 훈련 요약을 알려주세요." 어시스턴트가 get-training-summary를 호출하고 간결한 보고서를 반환합니다.

완전한 제어를 원하면 서버를 로컬로 실행할 수 있습니다:

npm install -g hevy-mcp   # npx/bunx/docker도 가능
export HEVY_API_KEY=your-key
npx -y hevy-mcp            # stdio MCP 서버 시작

클라이언트가 해당 명령을 실행하도록 구성합니다 (Claude Desktop, Cursor, Google Antigravity 등에 대한 README 참조).

에코시스템 및 도구

@chrisdoc/hevy-cli – Hevy API에 직접 연결하는 별도의 명령줄 클라이언트 (MCP 없음). 스크립팅 또는 빠른 데이터 덤프에 유용.
Claude 플러그인 – .claude-plugin/plugin.json 및 .mcp.json을 통해 Claude.ai가 OAuth로 호스팅 엔드포인트에 연결하여 Hevy 운동 스킬을 노출.
Docker 이미지 – ghcr.io/chrisdoc/hevy-mcp:latest (linux/amd64 및 linux/arm64 지원).
MCP 탑리스트 배지 – 공개 MCP 구현 중 서버 순위 표시.

사용 대상

피트니스 특화 AI 어시스턴트 – 개인 LLM 코치가 진행 상황을 분석하고 루틴 조정을 제안하거나 방금 완료한 운동을 기록.
맞춤 에이전트를 개발하는 개발자 – Hevy API 호출을 직접 만들지 않고 23개의 기성 도구 사용.
파워 유저 – hevy-mcp 서버를 다른 MCP 서비스(예: 영양 추적기)와 결합하여 통합 건강 어시스턴트 구축.

라이선스 및 기여

MIT 라이선스.
기여 환영. Cloudflare Worker 자체 호스팅, 새 도구 추가, 문서 개선에 대한 자세한 내용은 CONTRIBUTING.md 참조.

요약: hevy-mcp는 개인 Hevy 운동 데이터를 깔끔하고 AI 준비된 인터페이스로 변환하여, 모든 MCP 호환 어시스턴트에서 자연어 쿼리와 안전하고 확인된 변경 작업을 가능하게 합니다.