super-hevy-mcp

MCP server for the Hevy workout tracker — full API coverage, built for serious lifters. Ask Claude about your training history, log workouts, and manage routines straight from chat.

Requirements

• Node.js 20+

• A Hevy Pro subscription (the Hevy API requires Pro)

• A Hevy API key: https://hevy.com/settings?developer

Setup

Claude Code

claude mcp add super-hevy -e HEVY_API_KEY=<your-key> -- npx -y super-hevy-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "super-hevy": {
      "command": "npx",
      "args": ["-y", "super-hevy-mcp"],
      "env": { "HEVY_API_KEY": "<your-key>" }
    }
  }
}

Tools (v0.3)

Weights are kilograms. Workout sets accept RPE (6-10); routine sets accept rep_range targets. Responses are trimmed (no null noise) to keep context lean.

Analysis (v0.3)

Server-side aggregation tools that pre-crunch training metrics instead of making the LLM re-derive them from raw workout history.

• get-progressive-overload-report — "Is exercise X progressing?" Fetches GET /v1/exercise_history/{exerciseTemplateId} over a weeks-long window (default 12, 1-52), groups the logged sets by session (workout), and reports per session: top working-set weight, best estimated 1-rep max (e1RM), working-set count, and tonnage. Also returns an overall trend (first vs. last session e1RM, delta, % change, and the window's peak e1RM). Warmup sets are excluded from every metric — only working sets (normal/failure/dropset) count. e1RM uses the Epley formula: weight_kg * (1 + reps / 30).

• get-volume-by-muscle-group — "How many working sets / how much tonnage per muscle group per week?" (a volume-landmark check). Pages GET /v1/workouts over a weeks-long window (default 8, 1-52), attributes each working set to its exercise's primary muscle group (via GET /v1/exercise_templates/{id}, one fetch per distinct exercise used), and buckets sets/tonnage by ISO-8601 week. Only working sets (normal/failure/dropset) count — warmups are excluded. Tonnage is external weight_kg × reps only (bodyweight lifts still count as sets, at 0 tonnage). Exercises with no known muscle-group mapping are bucketed as "unknown" rather than dropped. Reports each muscle group's weekly_avg_sets/weekly_avg_tonnage_kg (averaged over the full requested window, so they're comparable to published volume landmarks) plus a per-week breakdown, sorted most-trained first. coverage.truncated: true means the workout fetch hit its page cap before covering the full window.

• get-training-frequency — "How many sessions per week, and how often do I train each muscle group?" Pages GET /v1/workouts over a weeks-long window (default 8, 1-52). sessions/weekly_sessions_avg count distinct workouts per ISO-8601 week. For each muscle group, avg_days_per_week counts distinct calendar days with at least one working set targeting that muscle's primary group (warmups excluded; training a muscle twice in one day still counts as one day). Averages are totals divided by the full requested weeks window. muscle_group_frequency is sorted most-trained first.

v0.3 completes the bodybuilding analysis layer (progressive overload, volume, and frequency). Roadmap: MCP prompts for guided workflows, and body-composition analytics.

Development

npm install
npm test          # unit + integration tests (mocked HTTP)
npm run smoke     # end-to-end against the real API (needs HEVY_API_KEY)
npm run build

License

MIT