mcp-server-hevy

MCP server for the Hevy strength-training API — workouts, routines, exercise history and progression data.

Self-hosted alternative to the public hosted Hevy MCP, built to the same shape as our other personal connectors: one shared instance, per-user credentials encrypted at rest, access gated by the identity the gateway verifies.

Independent, unofficial project. Not affiliated with Hevy.

Requirements

Hevy Pro. The Hevy developer API is only available to Pro subscribers — the API key simply doesn't exist on a free account, so nothing here will work without one.

How a user links their account

The key never passes through the conversation. Instead:

1. Ask Claude to connect Hevy → hevy_connect returns a one-time link
2. Open it, paste the Hevy API key into the form, submit
3. The server validates it against Hevy before storing it, so a wrong key fails immediately rather than as a confusing 401 later

The key is found at hevy.com/settings?developer — in a browser, not the mobile app.

This mirrors mcp-server-garmin: the enrollment route is reached directly (bypassing the gateway) and is secured by a single-use, user-bound state token. Unlike an OAuth code, a Hevy API key is long-lived, which is exactly why it shouldn't sit in a chat transcript.

Tools

Auth: hevy_connect, hevy_status, hevy_disconnect, hevy_search_capabilities

Read: hevy_get_workouts, hevy_get_workout, hevy_get_workout_count, hevy_get_workout_events (incremental sync), hevy_get_exercise_history, hevy_get_routines, hevy_get_routine, hevy_get_routine_folders, hevy_search_exercise_templates, hevy_get_exercise_template, hevy_get_user_info, hevy_get_body_measurements

Write (only registered when HEVY_ENABLE_WRITES=true): hevy_create_workout, hevy_update_workout, hevy_create_routine, hevy_update_routine, hevy_create_routine_folder, hevy_create_exercise_template

Hevy API constraints worth knowing

These are properties of Hevy's API, not choices made here:

• No DELETE, no PATCH. Nothing can be deleted through the API, and there is no partial update.
• PUT replaces the whole record. Any exercise or set omitted from an update is erased. Always read the current object first and resend it complete — the update tools are annotated destructiveHint for this reason.
• Creates are not idempotent. A retried create makes a duplicate, so this client retries GET only; failed writes surface to the caller instead of silently double-posting.
• Units are fixed: weights in kilograms, durations in seconds.
• Small pages. Max 10 per page for workouts/routines/folders, 100 for exercise templates.
• Hevy's own docs describe the API as unstable and subject to change.

Body measurements are read-only, deliberately

Hevy can store body weight and composition, and its API can write them — this server intentionally doesn't. Withings is the source of truth for body metrics in our setup; writing them here too would create a second competing record with no defined winner. Reading is exposed so existing Hevy data stays visible.

Configuration

HEVY_ENCRYPTION_KEY=        # AES-256-GCM key for the credential store (openssl rand -hex 32)
HEVY_STORE_PATH=/data/store.json
HEVY_PUBLIC_BASE_URL=       # public origin, used to build the enrollment link
HEVY_TRUST_FORWARDED_USER=true
HEVY_ENABLE_WRITES=true
HEVY_AUDIT_LOG=
HEVY_TIMEOUT_MS=30000
MCP_HTTP_TOKEN=

No app-level API credentials exist — every credential is per user.

Verification

npm run typecheck && npm test && npm run build

License

Apache-2.0