# Hevy Coach [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/gCuadros/hevy-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hevy-coach

## Description
Training analytics over your Hevy log: e1RM, PRs, volume, consistency, bodyweight.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hevy-coach": {
    "command": "npx",
    "args": ["-y","hevy-coach-mcp"]
  }
}
```

## Documentation & README

# hevy-coach-mcp

An MCP server for [Hevy](https://www.hevyapp.com/) (the workout tracking app). It fetches your workouts, routines and exercise templates live from Hevy — no local cache or database — then does the analytics math (e1RM, PRs, volume, consistency, period comparisons) so your MCP client can reason over real numbers instead of guessing. It writes back what you ask it to — routines, folders, a bodyweight — and never touches your workout history.

Requires **Hevy PRO** and a Hevy API key (Hevy app → Settings → API).

## Install

```
claude mcp add hevy -e HEVY_API_KEY=your_key_here -- npx -y hevy-coach-mcp
```

Or add it manually to your client's MCP config:

```json
{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "hevy-coach-mcp"],
      "env": { "HEVY_API_KEY": "your_key_here" }
    }
  }
}
```

This works in **Claude Desktop** (`claude_desktop_config.json`), **Claude Code** (`.mcp.json` or the command above), **Cursor** (`.cursor/mcp.json`), and **Windsurf** (`~/.codeium/windsurf/mcp_config.json`) — same shape everywhere.

Your API key stays local: it's read from the `HEVY_API_KEY` environment variable and never leaves your machine except in calls to Hevy's own API.

There's also a hosted mode over Streamable HTTP with OAuth, for clients that can't spawn a
local process (Claude.ai, ChatGPT). Point them at `https://hevy-mcp-alpha.vercel.app/mcp`
and they'll run the OAuth flow themselves. [docs/CONNECTOR.md](https://github.com/gCuadros/hevy-mcp/blob/HEAD/docs/CONNECTOR.md) covers
both setups client by client, plus self-hosting, example questions and privacy details.

## First use

Run `health-check` any time to confirm the connection. Every other tool fetches live from Hevy — there's nothing to sync or warm up first.

## Tools

Fifteen read tools, all marked `readOnlyHint`:

- `health-check` — connection status
- `get-workouts`, `get-workout` — list/inspect workouts
- `list-routines`, `get-routine` — list/inspect routines
- `list-routine-folders` — the folders routines are organised into, with their IDs
- `search-exercises`, `get-exercise-history` — resolve an exercise by name and see its logged history
- `get-progress`, `get-records` — estimated-1RM trend and PRs (1/3/5/8RM) per exercise; `get-progress` can also report each session against the bodyweight you were carrying
- `get-volume-report` — effective sets and tonnage per muscle group per week
- `get-consistency` — training frequency, streak, longest gap
- `compare-periods` — volume/workout-count diff between two date ranges
- `get-body-measurements` — logged bodyweight and measurements, newest first
- `get-bodyweight-trend` — weight change over a range: total, percentage and rate per week

Four write tools, declared as writes so your client asks first:

- `create-routine` — build a new routine from exercise names, optionally into a folder named rather than numbered
- `update-routine` — edit an existing routine; passing an exercise list replaces the old one outright (`destructiveHint`)
- `create-routine-folder` — add a folder; a title that already exists is never created twice
- `log-body-measurement` — record a bodyweight or measurement for a date you give it; re-logging a date keeps whatever else was stored that day

## Resources

`hevy://profile`, `hevy://routines`, `hevy://exercises`, `hevy://stats/summary`, `hevy://workouts/recent` — cheap live snapshots for a client to read without a tool call.

## Prompts

`weekly-review`, `program-audit`, `deload-check`, `prepare-session` — guide the client through calling the right tools for common training questions.

For the layer above those — a standing system prompt that turns the numbers into decisions — see [docs/COACH-PROMPT.md](https://github.com/gCuadros/hevy-mcp/blob/HEAD/docs/COACH-PROMPT.md).

## Privacy

Nothing about your account is stored — every tool call fetches fresh from Hevy's API using your own key, and nothing about your account is sent anywhere else.

Four tools write to Hevy: `create-routine`, `update-routine`, `create-routine-folder` and `log-body-measurement`, all declared as writes so your client asks before running them. **Nothing writes to your workout history** — that is the line, and it does not move: a logged workout is what every number here is computed from, so it can only be changed by you, in the app. Hevy's API has no delete endpoint, so nothing this server creates can be removed from here either. Note that a Hevy API key has no scopes — it grants full account access no matter what this server chooses to do with it.

## Contributing

Clone, `yarn install`, and copy `.env.example` to `.env.local`. Validate any change with
`yarn typecheck && yarn test && yarn build` — the same three commands CI runs.

[`AGENTS.md`](https://github.com/gCuadros/hevy-mcp/blob/HEAD/AGENTS.md) is the full guide to the architecture, conventions and the
decisions worth knowing before changing anything. It is written for AI coding agents, but
it is the fastest way for a human to get oriented too.

## License

MIT