hevy-mcp-server

Hevy 운동 기록 API용 MCP 서버입니다. LLM이 운동, 루틴, 운동 템플릿, 운동별 기록, 신체 측정값을 읽고 쓸 수 있게 해줍니다.

Hevy 공개 API(v0.0.1)의 15개 엔드포인트 전체를 27개 도구로 제공합니다.

요구 사항

• Node.js 18+

• Hevy Pro 구독 — API 접근은 Pro 전용입니다

• https://hevy.com/settings?developer에서 발급받은 API 키

Related MCP server: hevy-mcp-server

설치

pnpm install
pnpm run build

설정

MCP 클라이언트 설정에 HEVY_API_KEY를 설정하세요. Claude Desktop의 경우 claude_desktop_config.json에:

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp-server/dist/index.js"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

원격/HTTP 모드, 로컬에서:

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

도구를 대화형으로 검사:

HEVY_API_KEY=your-key pnpm run inspect

배포 (Claude 모바일 / claude.ai 커넥터용)

Claude는 사용자 기기가 아닌 Anthropic의 클라우드에서 커스텀 커넥터에 연결하므로, 모바일과 claude.ai에서는 이 서버가 공개 HTTPS로 접근 가능해야 합니다. Claude Code와 Claude Desktop은 그렇지 않으므로 대신 stdio를 사용하세요.

1. 경로 시크릿 생성

openssl rand -hex 32

MCP_PATH_SECRET이 설정되지 않은 상태에서 서버는 루프백이 아닌 인터페이스에서 시작을 거부합니다. Hevy 키를 보유한 공개 엔드포인트는 계정에 대한 오픈 프록시가 되기 때문입니다. 설정하면 엔드포인트가 /mcp/<secret>으로 이동하고 다른 모든 경로는 404를 반환합니다. 잘못된 시크릿도 마찬가지이므로, 호스트를 탐색해도 MCP 서버가 존재한다는 사실이 드러나지 않습니다.

2. 배포

포함된 Dockerfile과 railway.json은 Railway, Render, Fly에서 그대로 작동합니다. 이미지는 TRANSPORT=http와 HOST=0.0.0.0을 설정하고 비루트 사용자로 실행됩니다. 플랫폼 대시보드에서 두 변수를 설정하세요:

PORT는 플랫폼이 주입합니다. /healthz는 인증이 필요 없는 활성 상태 확인(liveness probe)입니다.

3. 검증

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. 커넥터 추가

claude.ai에서 브라우저로 — 커넥터는 모바일 앱에서 추가할 수 없습니다:

1. Customize → Connectors → Add custom connector

2. URL: https://your-app.up.railway.app/mcp/<secret>

3. 휴대폰에서 채팅을 열고 + → Connectors에서 활성화하세요

그 URL을 비밀번호처럼 취급하세요. 인터넷과 사용자의 운동 기록 사이를 지키는 유일한 장벽입니다. 유출되면 MCP_PATH_SECRET을 교체하고 커넥터를 다시 추가하세요.

도구

운동(Workouts) — hevy_list_workouts, hevy_get_workout, hevy_count_workouts, hevy_list_workout_events, hevy_create_workout, hevy_update_workout

세션(Sessions) — hevy_start_session, hevy_get_active_session, hevy_finish_session, hevy_cancel_session

루틴(Routines) — hevy_list_routines, hevy_get_routine, hevy_create_routine, hevy_update_routine

루틴 폴더(Routine folders) — hevy_list_routine_folders, hevy_get_routine_folder, hevy_create_routine_folder

운동 템플릿(Exercise templates) — hevy_search_exercise_templates, hevy_list_exercise_templates, hevy_get_exercise_template, hevy_create_exercise_template

진행 상황(Progress) — hevy_get_exercise_history, hevy_list_body_measurements, hevy_get_body_measurement, hevy_create_body_measurement, hevy_update_body_measurement

계정(Account) — hevy_get_user_info

모든 읽기 도구는 response_format: "markdown" | "json"을 받습니다. Markdown이 기본값이며 LLM이 읽기에 최적화되어 있습니다. JSON은 전체 구조화된 페이로드입니다. 형식과 관계없이 structuredContent는 항상 채워집니다.

예시

"이번 주에 뭐 운동했지?" → hevy_list_workouts에 page_size=5를 사용합니다. 세션별 제목, 시간, 운동 목록, 총 볼륨을 반환합니다.

"오늘 벤치 기록: 3x8 @ 60kg" → hevy_search_exercise_templates에 query="bench press"를 사용해 id를 얻은 다음, hevy_create_workout으로 { weight_kg: 60, reps: 8 } 세트 3개를 기록합니다.

"지금 하체 시작할게" → hevy_start_session에 title="Leg Day"를 사용합니다. 시작 시간은 서버 측에서 기록되며 세션은 Hevy에서 진행 중으로 표시됩니다. 끝나면 수행한 내용과 함께 hevy_finish_session을 호출하여 실제 시간으로 마무리합니다.

"스쿼트 실력이 늘고 있나?" → hevy_search_exercise_templates에 query="squat"를 사용한 다음, hevy_get_exercise_history에 start_date를 지정합니다. 기록된 모든 세트를 최신순으로 반환하고, 추정 1RM 기준 최고 세트도 반환합니다.

설계 노트

쓰기 전에 검색하세요. Hevy에는 서버 측 운동 검색이 없지만 모든 쓰기에는 exercise_template_id가 필요합니다. hevy_search_exercise_templates는 카탈로그를 페이지 단위로 탐색하며(최대 30페이지, 각 100개) 제목, 근육 그룹, 장비, 커스텀 전용을 기준으로 로컬에서 필터링합니다. 모델을 이 도구로 먼저 안내하세요 — id는 추측할 수 없습니다.

업데이트는 패치가 아닌 교체입니다. hevy_update_workout, hevy_update_routine, hevy_update_body_measurement는 리소스 전체를 덮어씁니다. 생략된 항목은 삭제되거나 null로 설정됩니다. 세 도구 모두 destructiveHint: true를 가지며, 설명에 모델이 먼저 현재 상태를 읽도록 안내합니다. 이 세 가지만이 파괴적 도구입니다 — Hevy API에는 삭제 엔드포인트가 없습니다.

라이브 세션은 서버 상태가 아닌 제목 규칙입니다. Hevy API에는 운동 시작 엔드포인트가 없고 앱 내 타이머를 구동할 수 없으므로, hevy_start_session은 🔴 In Progress — <title>이라는 제목의 실제 운동을 미리 생성하고, hevy_finish_session은 실제 종료 시간으로 다시 작성합니다. 그 표시가 유지되는 유일한 핸들입니다 — 서버는 요청 간 상태를 보유하지 않으므로, 어떤 기기의 어떤 채팅에서든 최근 운동을 스캔하여 열린 세션을 찾습니다. 단점은 완료되지 않은 세션이 로그에 계속 표시된다는 점이며, Hevy가 삭제를 제공하지 않으므로 hevy_cancel_session은 이름을 바꿀 수만 있고 제거할 수는 없습니다.

모든 것은 킬로그램입니다. API에는 단위 필드가 없습니다. 입력 필드 이름이 weight_kg이므로 모델이 무엇을 보내는지 모호함이 없고, 마크다운 출력은 둘 다 표시하므로(60 kg (132.3 lb)) 미국 사용자가 머리로 변환할 필요가 없습니다.

페이지 크기 상한은 클라이언트 측에서 적용됩니다. Hevy는 초과 크기 페이지에 대해 빈 400을 반환합니다. Zod 스키마가 각 엔드포인트를 문서화된 한도(대부분 10, 운동 템플릿은 100)로 제한하므로, 모델은 실패한 요청 대신 정확한 메시지를 받습니다.

오류는 다음 행동으로 이어집니다. 404는 해당 리소스에 유효한 id를 생성하는 도구를 알려줍니다. 신체 측정값의 409는 업데이트 도구를 가리킵니다. 403은 API 접근에 Pro가 필요함을 설명합니다.

허용적인 출력 스키마. Hevy 문서는 이 0.0.1 API가 예고 없이 구조를 변경할 수 있다고 경고합니다. 출력 스키마는 선택적 필드와 함께 passthrough()를 사용하여 상위 필드 추가가 하드 도구 실패로 이어지지 않게 합니다.

프로젝트 구조

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

주의 사항

• Hevy API는 공식적으로 버전 0.0.1이며 자체 문서에서도 구조가 변경되거나 중단될 수 있다고 경고합니다.

• 루틴의 폴더는 생성 후 변경할 수 없습니다 — 업데이트 엔드포인트가 folder_id를 받지 않습니다.

• 검색의 장비 필터링은 운동 제목을 기준으로 일치합니다. API가 템플릿에 장비를 필드로 노출하지 않기 때문입니다.

• hevy_create_exercise_template은 API의 다른 모든 곳에서 사용되는 문자열 id와 달리 숫자 id를 반환합니다.

테스트

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

두 테스트 스위트 모두 로컬 목(mock)으로 실행되므로 API 키나 네트워크 접근이 필요 없습니다.