Hevy Pro

A production-ready Model Context Protocol server for the Hevy fitness API. Exposes 27 tools for reading, writing, and analyzing your workout data — designed for "personal trainer via LLM" workflows in Claude Desktop, Claude Code, and Cursor.

CI npm version License: MIT

What sets this apart

Compared to the existing community Hevy MCP server, hevy-mcp-pro adds:

• Local analytics: progression series, personal records (Epley 1RM), volume summaries, frequency stats, and stagnation detection — computed locally from your data, not via the Hevy API.
• Smart fetching: single-exercise analytics use Hevy's /exercise_history endpoint (one call, full history) instead of paginating all workouts.
• Robust HTTP client: token-bucket throttling, exponential backoff with jitter on 429/5xx, honors Retry-After, and never logs your API key.
• Strict request validation: Zod schemas reject malformed payloads before they hit the Hevy API.
• Convenience tools: duplicate_workout, routine_from_workout, compare_workouts.

Requirements

• Node.js 20+
• A Hevy PRO subscription (required to obtain an API key)
• Your Hevy API key from hevy.com/settings?p=developer

Quick start

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@cdorneles/hevy-mcp-pro"],
      "env": {
        "HEVY_API_KEY": "your-key-here"
      }
    }
  }
}

Restart Claude Desktop and you should see "hevy" in the MCP tool picker.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@cdorneles/hevy-mcp-pro"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

Claude Code

claude mcp add hevy npx -- -y @cdorneles/hevy-mcp-pro
# then set HEVY_API_KEY in the resulting config

Tools

Reading

Tool	Purpose
list_workouts	Paginate workouts (max pageSize 10 — Hevy API limit)
get_workout	Fetch a single workout with all sets
get_workout_count	Total workout count for the account
get_workout_events	Sync incremental updates/deletes since a timestamp
list_routines	Paginate routines
get_routine	Fetch a single routine
list_exercise_templates	Paginate exercise templates
get_exercise_template	Fetch one template
search_exercise_templates	Local fuzzy search across all templates (cached)
get_exercise_history	Flat history of every set for one exercise
list_routine_folders	Paginate folders
get_routine_folder	Fetch one folder
get_user_info	Authenticated user profile

Writing

Tool	Purpose
create_workout	Log a new workout
update_workout	Modify an existing workout
create_routine	Create a routine template
update_routine	Modify an existing routine
create_routine_folder	Create a new folder
create_exercise_template	Create a custom exercise

Analytics

Tool	Purpose
get_exercise_progression	Time series of best set per session for one exercise
get_personal_records	PRs (heaviest weight, best set, top estimated 1RM)
get_volume_summary	Volume grouped by exercise / muscle group / week
get_workout_frequency	Workouts/week, current streak, longest gap
detect_stagnation	Exercises whose 1RM has plateaued in the last N weeks

Convenience

Tool	Purpose
duplicate_workout	Re-log a past workout starting now (or at a given time)
routine_from_workout	Convert a logged workout into a reusable routine
compare_workouts	Side-by-side diff of two workouts

Configuration

All configuration is via environment variables.

Variable	Required	Default	Description
HEVY_API_KEY	yes	—	Your Hevy API key
LOG_LEVEL	no	info	error | warn | info | debug
HEVY_RATE_LIMIT_CAPACITY	no	10	Token bucket capacity (max burst)
HEVY_RATE_LIMIT_REFILL_PER_SEC	no	10	Token refill rate (requests/sec)
HEVY_ANALYTICS_MAX_PAGES	no	50	Soft cap for analytics pagination (50 pages = 500 workouts)
HEVY_CACHE_TTL_MS	no	3600000	Exercise template cache TTL (default 1h)

Example prompts

Once installed, you can ask your LLM things like:

"Show me my bench press progression over the last 3 months."

"What are my current personal records on squats, deadlifts, and bench?"

"Detect any exercises where I've stagnated in the last 8 weeks."

"Duplicate yesterday's workout and start it now."

"Compare my last two leg days."

"How many times did I train chest in March?"

Troubleshooting

Invalid API key or Hevy PRO subscription required

Confirm you have a Hevy PRO subscription and that the key from hevy.com/settings?p=developer is correctly set in HEVY_API_KEY. The key never appears in logs, so a typo is the most common cause.

Rate limited by Hevy API (retries exhausted)

The default client-side throttle is 10 req/s. If you're running heavy analytics queries against a long workout history, lower HEVY_RATE_LIMIT_REFILL_PER_SEC to e.g. 5 to slow down further.

Analysis limited to first 500 workouts

Analytics tools paginate workouts with a soft cap. Raise HEVY_ANALYTICS_MAX_PAGES if you need to analyze deeper history. Each page is up to 10 workouts.

Logs

This server writes structured JSON logs to stderr (stdout is reserved for the MCP protocol). To debug, set LOG_LEVEL=debug and check your MCP client's server log view.

Development

git clone https://github.com/cbotworks/mcp-hevy-pro.git
cd hevy-mcp-pro
pnpm install
pnpm test       # 41+ unit tests, no network
pnpm typecheck
pnpm lint
pnpm build      # produces dist/ (ESM + CJS + .d.ts)

To regenerate the vendored OpenAPI snapshot:

pnpm fetch-openapi

Architecture

src/
├── client/         HTTP layer (rate limiter, retry, error mapping, paginator)
├── schemas/        Zod schemas for API requests + responses
├── tools/          Tool implementations grouped by domain
│   └── analytics/  Pure analyzers (progression, PRs, volume, frequency, stagnation)
├── utils/          Logger, errors, TTL cache
├── server.ts       MCP server: registers tools, wires stdio transport
└── index.ts        CLI entry: parses env, fails fast on missing API key

The HTTP client owns all network I/O. Tools never call fetch directly. Analytics tools are pure functions over data fetched via the client, which makes them trivially fixture-testable.

Contributing

Issues and PRs welcome. Please run pnpm typecheck && pnpm lint && pnpm test before submitting.

License

MIT — see LICENSE.

Acknowledgements

The Hevy team for the public API. The community chrisdoc/hevy-mcp server informed early API exploration but no code was reused.