@cdorneles/hevy-mcp-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.

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

Writing

Analytics

Convenience

Configuration

All configuration is via environment variables.

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.