# super-hevy-mcp

MCP server for the [Hevy](https://hevy.com) 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

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

### Claude Desktop

Add to `claude_desktop_config.json`:

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

## Tools (v0.3)

| Tool | Description |
| --- | --- |
| `get-user-info` | Your Hevy profile |
| `list-workouts` | Logged workouts, most recent first (`limit` up to 100) |
| `get-workout` | One workout with all exercises and sets |
| `get-workout-count` | Total workouts on the account |
| `get-workout-events` | Workout updates/deletes since a date (for syncing) |
| `create-workout` | Log a completed workout |
| `update-workout` | Replace a workout's contents |
| `list-routines` | Saved routines (`limit` up to 100) |
| `get-routine` | One routine with prescribed sets |
| `create-routine` | Create a routine |
| `update-routine` | Replace a routine's contents |
| `list-exercise-templates` | Exercise library (built-in + custom), `limit` up to 100 |
| `get-exercise-template` | One exercise template by ID |
| `create-exercise-template` | Create a custom exercise template |
| `list-routine-folders` | Folders used to organize routines (`limit` up to 100) |
| `get-routine-folder` | One routine folder by ID |
| `create-routine-folder` | Create a routine folder |
| `get-exercise-history` | Every logged set for one exercise, across workouts (progression analysis) |
| `list-body-measurements` | Logged body measurements (`limit` up to 100) |
| `get-body-measurement` | One measurement entry by date |
| `create-body-measurement` | Log a new measurement entry for a date |
| `update-body-measurement` | Replace a measurement entry's contents |
| `get-progressive-overload-report` | Top-set/e1RM trend for one exercise, by session |
| `get-volume-by-muscle-group` | Working sets/tonnage per muscle group per week |
| `get-training-frequency` | Sessions per week and days/week trained per muscle group |

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

```bash
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