hevy-mcp

Ask Claude about your training, and let it build your Hevy routines.

hevy-mcp is a Model Context Protocol server that connects Claude to a Hevy account. It runs as a free Cloudflare Worker, so it works as a custom connector in Claude on the web, on desktop, and in the mobile app.

• Your full training history, analyzed properly. Volume that matches Hevy's own totals to the gram, working sets apart from warm-ups, personal records, and muscle balance.

• Routines written straight into Hevy. Claude picks real exercises from Hevy's library, shows you exactly what it will save, and writes it only after you agree.

• Programs longer than the free plan allows. Free Hevy accounts hold four routines. Plans live on the connector and load into Hevy one day at a time, and a whole folder can be set aside and brought back exactly as it was.

What it's like to use

Illustrative examples. The connector answers from your own data.

You: How has my bench press moved since the summer?

Claude: (reads 3 months of bench sets) Your top working set went from 125 × 8 in July to 140 × 8 last week, about 12% in 12 weeks. Volume dipped in late August when you trained twice a week instead of three times.

You: Which muscles am I neglecting?

Claude: (compares primary and secondary muscle exposure over 90 days) Glutes and calves never show up as a primary muscle. Glutes only get indirect work from leg press. A hip thrust or Romanian deadlift once a week would close most of that gap.

You: Save my PPL folder, then replace it with a 4-week upper/lower block. Leave the weights empty.

Claude: Saved "PPL" (3 routines, 73 sets) as a plan. Here's week 1 as it will appear in Hevy... (preview) Shall I write it?

You: Yes. And bring PPL back when the block is over.

Related MCP server: Boostcamp MCP Server

What Claude can do with it

23 tools in all. The full reference is in docs/TECHNICAL.md.

How it works

flowchart LR
    subgraph Claude["Claude: web, desktop, mobile, Claude Code"]
        C[Custom connector]
    end
    subgraph CF["Cloudflare Worker (free plan)"]
        A["OAuth 2.1<br/>sign-in"]
        M["MCP server<br/>23 tools"]
        S["Hourly sync<br/>(Cron Trigger)"]
        D[("D1 / SQLite<br/>workouts, plans,<br/>exercise library,<br/>Hevy login")]
        K[("KV<br/>OAuth grants")]
    end
    H["Hevy API<br/>api.hevyapp.com"]

    C -- "Streamable HTTP + bearer token" --> M
    C -. "first connection" .-> A
    A --- K
    M -- "history queries" --> D
    M -- "routines (live, allowlisted)" --> H
    S -- "new and edited workouts" --> H
    S --> D

• History is synced into D1 every hour and queried locally, so questions are fast and never touch Hevy. Routines are read live, because you edit them in the app too.

• Sign-in: claude.ai finds the authorization server through the 401 response, identifies itself with Anthropic's published client metadata, and sends you to the connector's own sign-in page once. After that it renews its own tokens.

• The Hevy login lives only in the database. Hevy rotates its refresh token on every use, so one copy, guarded by a lease, is the only safe arrangement.

Engineering highlights

• A protocol mapped by observation, not guesswork. Read endpoints come from the hevy-unofficial package. Routine writes were recorded from hevy.com's own editor with a Playwright script that strips credentials before saving anything. Hevy's exercise library isn't in its API at all; it's extracted from the web app's bundle.

• Writes are allowlisted. Every non-GET request is checked against the exact routine and folder endpoints before it leaves. No code path can create, edit or delete a workout, and a test asserts it.

• Volume that reconciles with Hevy exactly. Hevy adds bodyweight to some exercises' volume using a figure that isn't in the workout data. Solving for it from the history makes every workout match Hevy's estimated_volume_kg to 0.000000 kg.

• A port proven equivalent. The connector began as a local Python server and was ported to TypeScript. Equivalence tests replay the real history through both: every payload hash matches byte for byte (Python's json.dumps and banker's rounding are reproduced exactly), every normalized row matches, and 28 recorded queries return identical output.

• A complete OAuth 2.1 server on Cloudflare's workers-oauth-provider, with:

  • PKCE, and Client ID Metadata Documents, so the page can show the request really is Claude;

  • a redirect allowlist that admits only claude.ai, claude.com and loopback;

  • PBKDF2-hashed credentials and rate-limited attempts.

• Concurrency handled explicitly. A lease in D1 serializes every use of the rotating Hevy token across the cron job and interactive tools. Two overlapping refreshes would revoke each other.

• A real bug, found in real use. Workouts were dated in UTC, which put every evening session on the next day: a third of the history. Fixed with time-zone-aware dates, migrated in place, and covered by tests for winter time and the midnight boundary.

• Free-tier engineering. The free Workers plan allows 50 outbound requests per run, so sync checkpoints and resumes, and the history was seeded from the local cache rather than re-downloaded. Hosting costs $0.

• 345 tests across Python (pytest) and TypeScript (Vitest). They run offline against a stateful fake of Hevy built from recorded requests, plus an in-memory D1 and KV.

Set up your own

You'll need a Hevy account, a free Cloudflare account with a domain on it (the connector needs a subdomain such as hevy.example.com), Node.js 24, Python 3.12+ and uv.

The helper scripts are PowerShell and were written on Windows. On macOS or Linux, use PowerShell 7 or run the commands inside them by hand; they're short.

1. Get the code and log in to Hevy locally

git clone https://github.com/rishikk99/hevy-mcp; cd hevy-mcp
uv sync
uv run hevy-mcp-authenticate   # opens a browser: log in by hand (Hevy's login has a CAPTCHA)
uv run hevy-mcp-sync           # downloads your history into .hevy/hevy.sqlite3

2. Fill in your settings. Set your time zone and the bodyweight from your Hevy profile in worker/src/config.ts and src/hevy_mcp/config.py (the blocks marked Your settings).

3. Create the Cloudflare pieces. Create an API token from the Edit Cloudflare Workers template, plus D1: Edit and Zone DNS: Edit for your domain. Save it as the environment variable CLOUDFLARE_API_TOKEN. Then:

cd worker
npm ci
npx wrangler d1 create hevy                 # copy the database_id it prints
npx wrangler kv namespace create OAUTH_KV   # copy the id it prints

Put both IDs and your subdomain into the lines marked YOURS in worker/wrangler.jsonc.

4. Create the database and load it

npx wrangler d1 migrations apply hevy --remote
uv run python scripts/update_exercise_library.py library.sql   # Hevy's exercise library
npx wrangler d1 execute hevy --remote --file library.sql
uv run python scripts/export_to_d1.py history.sql              # your history, from step 1
npx wrangler d1 execute hevy --remote --file history.sql
Remove-Item library.sql, history.sql                           # personal data: don't keep it

5. Deploy, choose a password, and hand over the Hevy login

If Windows refuses to run the scripts, prefix each with powershell -ExecutionPolicy Bypass -File.

npx wrangler deploy
.\set-password.ps1    # prompts twice; only a PBKDF2 hash is uploaded
.\push-login.ps1      # moves your Hevy login into the database, then deletes the local copy

6. Connect Claude. On claude.ai, go to Settings → Connectors → Add custom connector and enter https://<your-subdomain>/mcp. Claude detects the sign-in, opens your password page once, and the connector then works on the web, on desktop and on your phone.

If Hevy ever logs you out, Claude says so. Run .\worker\push-login.ps1 again; it opens the Hevy login, checks it, and sends it up.

Local mode

The original Python server still works on its own over stdio, for Claude Desktop or Claude Code without any hosting. It covers the history and analysis tools (read-only) and an authenticate tool that runs the browser login:

{ "mcpServers": { "hevy": { "command": "uv", "args": ["--directory", "/path/to/hevy-mcp", "run", "hevy-mcp"] } } }

Hevy rotates refresh tokens, so a login can live in one place only. Once it has been pushed to the Worker, use the hosted connector everywhere.

Development

uv run pytest                    # Python: 173 tests
cd worker; npm test              # TypeScript: 172 tests
npx tsc --noEmit                 # type check

Everything runs offline. Tests that compare the two implementations need your local history (.hevy/hevy.sqlite3, and worker/test/.golden.json from uv run python worker/test/golden_queries.py) and skip themselves without it, as in CI.

src/hevy_mcp/     Python: Hevy client, browser login, sync, normalization, queries, stdio server
worker/src/       TypeScript Worker: OAuth sign-in, MCP handler, tools, sync, plans
worker/migrations D1 schema
worker/scripts/   exercise library extraction, history export, time zone migration
scripts/          capture tools used to record Hevy's request shapes
docs/             technical reference and images

How it works in depth (sync, schema, volume rules, authentication, every tool): docs/TECHNICAL.md.

Security and privacy

• Nothing personal is in this repository. Workout data, the Hevy login, the connector password and API tokens all live in .hevy/ (gitignored), in Cloudflare secrets, or in your environment. Committed test fixtures are sanitized.

• One owner per deployment. Each person runs their own copy on their own Cloudflare account, so nobody hands their Hevy login to anyone else.

• Sign-in:

  • OAuth 2.1 with PKCE;

  • access tokens can only be sent to Claude's own addresses;

  • ten wrong passwords pause sign-in for an hour;

  • the password is stored only as a PBKDF2 hash.

• Every change to your Hevy account is previewed and confirmed. The Claude apps can also be set to ask permission before any tool that changes something runs.

Credits

Read endpoints and the token refresh flow follow Sahil624/hevy-unofficial. Hevy is a trademark of its owners; this project is independent of them.

License

MIT