hevy-mcp

Claude를 Hevy 운동 로그와 연결하세요.

hevy-mcp는 Claude(데스크톱 또는 claude.ai)가 사용자의 운동 기록을 읽고, 새로운 루틴을 설계하며, Hevy 라이브러리에 저장하고, 훈련 추세를 분석할 수 있게 해주는 Model Context Protocol 서버입니다. 이는 ChatGPT 사용자가 Hevy의 공식 통합 기능을 통해 얻는 것과 동일한 수준의 접근 권한을 제공합니다.

You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
      I've trained least over the last 30 days, and save it in a folder called
      'Hypertrophy Block 1'."

Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
        ✓ created folder "Hypertrophy Block 1"
        ✓ resolved 22 exercises against Hevy's library
        ✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
        Open the Hevy app to start any of them.

Claude에게 요청할 수 있는 작업

• 과거 기록 확인 — "지난 10번의 운동을 보여주고 내가 소홀히 했던 근육 그룹이 무엇인지 알려줘."

• 계획 수립 — "내 벤치 프레스 기록을 바탕으로 내일 수행할 적절한 탑 세트(top set)는 무엇일까?"

• 루틴 구성 — "4일 분할 상/하체 비대 운동 루틴을 짜서 저장해줘."

• 루틴 편집 — "'푸시 데이 A'에서 덤벨 숄더 프레스를 바벨 오버헤드 프레스 5회 4세트로 바꿔줘."

• 분석 — "주요 리프트의 1RM을 추정하고 지난 90일간의 스쿼트 진행 상황을 차트로 그려줘."

요구 사항

• Hevy PRO 구독 (개발자 API 사용을 위해 필요합니다).

• Hevy API 키 — https://hevy.com/settings?developer에서 발급받으세요.

• Python 3.11+ 또는 Docker.

• Claude Desktop 또는 사용자 지정 커넥터를 지원하는 claude.ai 작업 공간.

빠른 시작 — Claude Desktop (5분 소요)

1. 설치

# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp

# Or with pipx:
pipx install hevy-mcp

# Or with plain pip:
python -m pip install hevy-mcp

2. Claude Desktop에 추가

Claude Desktop의 설정 파일을 엽니다:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• Linux — ~/.config/Claude/claude_desktop_config.json

mcpServers 아래에 hevy 항목을 추가합니다 (파일이 없으면 생성하세요):

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_paste_your_key_here"
      }
    }
  }
}

hevy-mcp가 PATH에 없는 경우(uv-tool 설치 시 Claude Desktop 런처가 인식하지 못할 때가 있음), which hevy-mcp 명령어로 얻은 절대 경로를 사용하세요 (예: /Users/you/.local/bin/hevy-mcp).

3. Claude Desktop 재시작

완전히 종료한 후(macOS에서는 ⌘Q) 다시 엽니다. 도구 표시기에 hevy 서버가 연결되었음을 나타내는 아이콘이 표시되어야 합니다.

4. 테스트

"hevy 도구를 사용해서 내 마지막 운동 3개를 가져와서 요약해줘."

Claude가 실제 운동 기록을 보여준다면 성공입니다. 🎉

대안 — claude.ai (원격 커넥터)

Claude Desktop 대신 브라우저에서 claude.ai를 사용하는 경우, hevy-mcp를 HTTP 서비스로 실행하고 사용자 지정 커넥터로 추가하세요.

1. HTTPS가 지원되는 환경에서 서버 실행

가장 간단한 방법은 Fly.io / Render / Railway에서 Docker를 사용하는 것입니다:

docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcp

또는 CLI를 통해 직접 실행:

hevy-mcp --http --host 0.0.0.0 --port 8000

MCP 엔드포인트는 /mcp에 있습니다.

2. 사용자 지정 커넥터로 추가

claude.ai에서 **설정(Settings) → 커넥터(Connectors) → 사용자 지정 커넥터 추가(Add custom connector)**로 이동하여 /mcp로 끝나는 공개 HTTPS URL(예: https://hevy-mcp.fly.dev/mcp)을 입력하세요.

다중 사용자 참고 사항

여러 사용자가 동일한 배포 환경을 공유하는 경우, HEVY_API_KEY를 컨테이너 환경 변수에 고정하지 말고 요청별 헤더로 전달하세요. 서버는 X-Hevy-Api-Key가 있으면 이를 읽고, 없으면 환경 변수를 사용합니다. 서버 앞단에 인증을 주입하는 리버스 프록시(Cloudflare Worker, Nginx)를 두는 것이 일반적인 패턴입니다.

기능 목록 (전체 도구 목록)

내부 작동 방식:

• 스마트 캐싱 — 운동 라이브러리는 한 번 가져온 후 24시간 동안 캐싱되며, 퍼지 검색은 메모리 내에서 실행됩니다.

• 속도 제한 인식 — 429 오류 발생 시 대기하며 Retry-After를 준수합니다.

• 멱등성 쓰기 — 같은 폴더에 중복된 제목으로 루틴을 생성할 경우 Claude에게 확인을 요청합니다.

• LLM 친화적 오류 — 모든 오류는 { error, hint } 형태로 반환됩니다. 힌트는 다음 단계의 구체적인 도구 호출을 제안합니다.

• API 키를 절대 로그에 남기지 않습니다.

문제 해결

가장 흔한 원인: claude_desktop_config.json의 command가 런처의 PATH에 없는 경우입니다. "command": "hevy-mcp"를 which hevy-mcp(Windows의 경우 where hevy-mcp)로 확인한 절대 경로로 바꾸세요. Claude Desktop을 재시작하세요.

• 키를 args 블록이 아닌 env 블록에 붙여넣었는지 확인하세요.

• Hevy PRO 구독이 활성화되어 있는지 확인하세요.

• https://hevy.com/settings?developer에서 키를 새로 발급받아 다시 시도하세요.

search_exercise_templates는 퍼지 검색을 지원하지만 완벽하지는 않습니다. Claude가 잘못된 운동을 선택하면 "더 구체적인 이름으로 다시 검색해줘"라고 요청하거나 equipment 필터(예: "barbell")를 전달하세요.

운동 라이브러리는 첫 조회 시에만 가져오며(약 200ms 소요), 그 이후의 모든 호출은 메모리 내 캐시를 사용합니다. 캐시는 24시간 동안 유지됩니다.

개발

git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev          # creates .venv and installs deps
pytest -q                    # offline tests (no real API needed)

# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py

# Stdio (Claude Desktop):
hevy-mcp

# HTTP (claude.ai):
hevy-mcp --http --port 8000

더 자세한 내용은 CONTRIBUTING.md를 참조하세요.

프로젝트 구조

hevy-mcp/
├── src/hevy_mcp/
│   ├── server.py        # transport bootstrap (stdio + streamable-http)
│   ├── hevy_client.py   # async httpx client w/ retries & error mapping
│   ├── schemas.py       # Pydantic models
│   ├── cache.py         # 24-hour TTL cache
│   ├── errors.py        # HevyApiError + tool_guard
│   ├── formatters.py    # JSON → readable text
│   └── tools/           # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── Dockerfile

릴리스

CHANGELOG.md를 참조하세요. 태그가 지정된 릴리스는 자동으로 PyPI에 게시됩니다.

라이선스

MIT.

감사

이 프로젝트의 설계는 두 가지 초기 커뮤니티 구현체인 chrisdoc/hevy-mcp(TypeScript)와 SrdjanCodes/hevy-mcp(Python)에서 아이디어를 얻었습니다. 포크는 아니지만, 다른 언어나 기능 조합을 원하신다면 참고할 가치가 있습니다.

hevy-mcp는 커뮤니티 프로젝트이며 Hevy와 제휴하거나 보증을 받지 않습니다.