Provides tools for reading workout history, designing and saving routines, and analyzing training trends via the Hevy API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hevy-mcp Show me my last 5 workouts with details"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect Claude to your Hevy workout log.
hevy-mcp is a Model Context Protocol server that lets Claude (Desktop or claude.ai) read your workouts, design new routines, save them to your Hevy library, and analyze your training trends — the same kind of access ChatGPT users get from Hevy's official integration.
You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
I've trained least over the last 30 days, and save it in a folder called
'Hypertrophy Block 1'."
Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
✓ created folder "Hypertrophy Block 1"
✓ resolved 22 exercises against Hevy's library
✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
Open the Hevy app to start any of them.Look back — "Show me my last 10 workouts and tell me which muscle groups I've been neglecting."
Plan ahead — "Based on my bench press history, what's a good top set for tomorrow?"
Build routines — "Build me a 4-day upper/lower hypertrophy split and save it."
Edit routines — "On 'Push Day A', swap dumbbell shoulder press for a barbell overhead press, 4 sets of 5."
Analyze — "Estimate my 1RM on the main lifts and chart squat progression over the last 90 days."
Related MCP server: hevy-mcp
A Hevy PRO subscription (the developer API requires it).
Your Hevy API key — get it at https://hevy.com/settings?developer.
Either Python 3.11+ or Docker.
Claude Desktop, or a claude.ai workspace that supports custom connectors.
# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp
# Or with pipx:
pipx install hevy-mcp
# Or with plain pip:
python -m pip install hevy-mcpOpen Claude Desktop's config file:
macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
Linux — ~/.config/Claude/claude_desktop_config.json
Add the hevy entry under mcpServers (create the file if it doesn't exist):
{
"mcpServers": {
"hevy": {
"command": "hevy-mcp",
"env": {
"HEVY_API_KEY": "sk_live_paste_your_key_here"
}
}
}
}If
hevy-mcpisn't on your PATH (uv-tool installs sometimes aren't picked up by the Claude Desktop launcher), use the absolute path you get fromwhich hevy-mcp— for example/Users/you/.local/bin/hevy-mcp.
Quit fully (⌘Q on macOS) and reopen. You should see a tools indicator showing the hevy server is connected.
"Use the hevy tool to fetch my last 3 workouts and summarize them."
If Claude shows your real workouts, you're done. 🎉
If you use claude.ai in the browser instead of Claude Desktop, run hevy-mcp as an HTTP service and add it as a custom connector.
The simplest path is Docker on Fly.io / Render / Railway:
docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcpOr directly with the CLI:
hevy-mcp --http --host 0.0.0.0 --port 8000The MCP endpoint is at /mcp.
In claude.ai, go to Settings → Connectors → Add custom connector and use your public HTTPS URL ending in /mcp (e.g. https://hevy-mcp.fly.dev/mcp).
If multiple users will share the same deployment, don't bake HEVY_API_KEY into the container env — instead, send it as a per-request header. The server reads X-Hevy-Api-Key if present and falls back to the env var. A small auth-injecting reverse proxy (Cloudflare Worker, Nginx) in front of the server is the usual pattern.
Group | Tool | What it does |
Workouts |
| Page through your workout history, newest first. |
| Full detail of one workout — every set, rep, weight, RPE, note. | |
| Total workouts logged. | |
| Stream of created/updated/deleted events since a timestamp. | |
| Log a completed workout. | |
| Edit an already-logged workout. | |
Routines |
| Read your saved routines. |
| Save a new routine (with duplicate-title protection). | |
| Modify an existing routine. | |
Folders |
| Organize routines. |
Exercise library |
| Fuzzy search Hevy's ~400-exercise library by name, equipment, or muscle. |
| Browse/look up exercises. | |
Webhooks |
| One subscription per key (Hevy limit). |
Analytics |
| Epley/Brzycki e1RM from your top working sets. |
| Tonnage per muscle group over a window. | |
| e1RM-vs-time series for a single lift, with weekly slope. |
Under the hood:
Smart caching — the exercise library is fetched once and cached for 24 hours; fuzzy search runs in memory.
Rate-limit aware — backs off on 429s and honors Retry-After.
Idempotent writes — creating a routine with a duplicate title in the same folder asks Claude to confirm before doubling.
LLM-friendly errors — every error comes back as { error, hint }. The hint suggests the next concrete tool call.
Never logs your API key.
Most common cause: the command in claude_desktop_config.json isn't on the launcher's PATH. Replace "command": "hevy-mcp" with the absolute path from which hevy-mcp (or where hevy-mcp on Windows). Restart Claude Desktop.
Check that you pasted the key into the env block (not the args block).
Confirm your Hevy PRO subscription is active.
Rotate your key at https://hevy.com/settings?developer and try again.
search_exercise_templates is fuzzy but not magic. If Claude picks the wrong exercise, ask it to "search again with a more specific name" or pass an equipment filter (e.g. "barbell").
The exercise library is fetched on the first lookup (one-time, ~200ms). Every call after that hits the in-memory cache. The cache lasts 24 hours.
git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev # creates .venv and installs deps
pytest -q # offline tests (no real API needed)
# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py
# Stdio (Claude Desktop):
hevy-mcp
# HTTP (claude.ai):
hevy-mcp --http --port 8000See CONTRIBUTING.md for the longer version.
hevy-mcp/
├── src/hevy_mcp/
│ ├── server.py # transport bootstrap (stdio + streamable-http)
│ ├── hevy_client.py # async httpx client w/ retries & error mapping
│ ├── schemas.py # Pydantic models
│ ├── cache.py # 24-hour TTL cache
│ ├── errors.py # HevyApiError + tool_guard
│ ├── formatters.py # JSON → readable text
│ └── tools/ # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── DockerfileSee CHANGELOG.md. Tagged releases publish to PyPI automatically.
MIT.
This project's design owes ideas to two earlier community implementations: chrisdoc/hevy-mcp (TypeScript) and SrdjanCodes/hevy-mcp (Python). Not a fork — but worth a look if you want a different language or feature mix.
hevy-mcp is a community project and is not affiliated with or endorsed by Hevy.
Create a new routine.
Required routine shape:
{ title, folder_id?, notes?, exercises: [
{ exercise_template_id, rest_seconds?, notes?, sets: [
{ type, weight_kg?, reps?, rpe? }
] }
] }
WORKFLOW for natural-language requests:
Resolve every exercise name to a template id with search_exercise_templates.
(Optional) Create or look up the target folder with the folder tools.
Call this tool. If a routine with the same title already exists in the
folder you'll get back a duplicate_of payload — confirm with the user,
then re-call with force=True (or call update_routine instead).
Inputs: routine (required), force. Returns: object
Create a new routine folder. Returns the new folder including its id, which
you can pass to create_routine as folder_id.
Inputs: title (required). Returns: object
Create or replace the user's webhook subscription.
url: HTTPS endpoint Hevy will POST events to.
event_type: e.g. "workout_created". Hevy only accepts one subscription per key.
Inputs: url (required), event_type. Returns: object
Log a completed workout to Hevy.
workout shape:
{ title, description?, start_time, end_time, is_private?, exercises: [
{ exercise_template_id, notes?, superset_id?, sets: [
{ type, weight_kg?, reps?, rpe?, distance_meters?, duration_seconds? }
] }
] }
Resolve exercise_template_id values via search_exercise_templates before
calling this tool — never invent IDs.
Inputs: workout (required). Returns: object
Delete the active webhook subscription.
Inputs: no named parameters. Returns: object
Estimate the user's 1RM on a given exercise from their recent top sets.
Walks the user's workouts (newest first), gathers every set of the target exercise, and applies a strength formula:
"epley": weight * (1 + reps/30)
"brzycki": weight * 36 / (37 - reps)
Returns the highest e1RM observed plus the contributing set, plus a short recent history. Skips warmups and reps>15 (formulas are unreliable past that).
Inputs: exercise_template_id (required), method, max_pages. Returns: object
Fetch a single exercise template by id (the Hevy library entry, not a logged set).
Inputs: template_id (required). Returns: object
Fetch a single routine with every exercise and target set.
Inputs: routine_id (required). Returns: object
Fetch a single routine folder by id.
Inputs: folder_id (required). Returns: object
Return the user's current webhook subscription, if any.
Inputs: no named parameters. Returns: object
Fetch a single workout with every set, rep, weight, RPE, and note.
Use this when the user asks about a specific workout or wants to compare
sets across sessions. Pair with list_workouts to discover the id first.
Inputs: workout_id (required). Returns: object
Total number of workouts the user has logged. Cheap; safe to call eagerly.
Inputs: no named parameters. Returns: object
Stream of workout change events (created/updated/deleted).
Use to detect new workouts since a previous interaction without re-paginating
the full list. The since parameter is ISO-8601 (e.g. 2025-01-01T00:00:00Z).
Inputs: page, page_size, since. Returns: object
Paginated browse of the Hevy exercise library (~400 entries). Cached for 24h.
Prefer search_exercise_templates when looking up a specific exercise — it's
far faster than scanning pages.
Inputs: page, page_size. Returns: object
List the user's routine folders (e.g. 'Push/Pull/Legs', 'Hypertrophy Block').
Inputs: page, page_size. Returns: object
List the user's saved routines (templates they follow). Paginated.
Inputs: page, page_size. Returns: object
List the user's workouts in reverse-chronological order.
Use this first when the user asks about "recent workouts", "last N sessions",
"what did I train on Monday", etc. Each item is a summary; call
get_workout(workout_id) for full set-by-set detail when the user asks
about specific weights, RPE, or progression.
Inputs: page, page_size. Returns: object
Top-set e1RM over time for a single exercise. Returns a per-session series suitable for charting.
Inputs: exercise_template_id (required), since, max_pages. Returns: object
Fuzzy-search the Hevy exercise library. Use this before create_routine
or create_workout — it returns the exercise_template_id you need.
query: free-text exercise name. e.g. "barbell back squat", "incline db press".
equipment: optional filter, e.g. "barbell", "dumbbell", "cable", "machine", "bodyweight".
muscle_group: optional filter on primary_muscle_group, e.g. "chest", "lats", "quads".
Returns ranked candidates with id, title, equipment, primary_muscle_group, and a match score 0-100. Pick the top hit unless the user disambiguates.
Inputs: query (required), equipment, muscle_group, limit. Returns: object
Update an existing routine in place.
Same payload shape as create_routine.routine, with one important caveat:
Hevy's PUT endpoint does NOT accept folder_id, and there is no public API
endpoint for moving a routine between folders. If folder_id is present in
the payload it is silently stripped and a warning is included in the
response. To 'move' a routine, create a new copy in the target folder and
delete the old one in the Hevy app.
Inputs: routine_id (required), routine (required). Returns: object
Replace the contents of an existing logged workout. Same payload shape as create_workout.
Inputs: workout_id (required), workout (required). Returns: object
Aggregate working-set volume (kg lifted) by primary muscle group over a window.
Useful for "which muscle groups have I been neglecting?" prompts. Volume per set = weight_kg * reps; warmups excluded. Requires the template list to be loaded (it will be cached on first call).
Inputs: since, until, max_pages. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 22 tools
Each tool targets a distinct resource and action: routines, folders, workouts, webhooks, exercises, and analytics. No overlapping functionality; an agent can clearly distinguish between them.
All tool names follow a consistent verb_noun pattern (e.g., create_routine, list_workouts, get_exercise_template). No mixing of conventions or vague verbs.
With 22 tools, the set is slightly larger than typical but well-justified for a fitness tracking API covering CRUD, webhooks, and analytical operations. It remains scoped and manageable.
Missing delete operations for routines and workouts, and no update/delete for routine folders. This creates dead ends where agents cannot fully manage resources, limiting practical workflow completion.
Talk to your own gym log. Reps: Gym Workout Log (repsworkout.com) is a workout log for iPhone and Android. Connect it to Claude, ChatGPT or any MCP client to read your workout history, PRs, lift progression, weekly summaries, routines and training plan, and to save routines and plans after you confirm them. It never logs a workout for you and can’t delete your history. Sign in with an e-mail code, Apple or Google; new users can create a free account while connecting, then get the app to log workouts.
Connect Claude, Cursor or any MCP client to your GymUp training data.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Workout journal Claude and ChatGPT write to: log workouts, get a program, see your progress.
