Hevy Coach MCP server

hevy-coach-mcp

An MCP server for Hevy (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:

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

This works in Claude Desktop (claudedesktopconfig.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 HEVYAPIKEY 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 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.

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.

Shortened. The full README is on GitHub.