hevy-mcp

A small, self-hosted MCP server on Cloudflare Workers that lets Claude read your Hevy training data and manage routines through a custom connector.

• Reads: workouts, workout events, routines, routine folders, exercise templates, exercise history

• Writes: routines only (create and update). Workouts are read-only in v1.

• No database, no Durable Objects, no OAuth. One Worker, two secrets.

How it works

flowchart LR
    C[Claude custom connector] -->|HTTPS POST /mcp/<token>| W[Cloudflare Worker]
    W -->|token mismatch| X[404]
    W -->|token ok| H[createMcpHandler<br/>agents/mcp/server]
    H --> S[McpServer<br/>12 tools]
    S -->|api-key header| A[Hevy API<br/>api.hevyapp.com/v1]

The Worker is stateless: every request builds a fresh McpServer, checks the path token in constant time, and proxies tool calls to Hevy with your API key. Anything that is not /mcp/<token> gets a 404, so the URL itself is the only credential a client needs.

Related MCP server: Boostcamp MCP Server

Tools

Routine write bodies follow the Hevy spec exactly. Set fields are type (warmup, normal, failure, dropset), weight_kg, reps, distance_meters, duration_seconds, custom_metric and rep_range. There is no rpe field on routine sets.

Setup

Requirements: Node 22+, a Cloudflare account, and a Hevy Pro subscription (the API key lives at hevy.com > Settings > Developer).

npm install
npx wrangler login

# Secrets never go in code. Set them on the Worker:
npx wrangler secret put HEVY_API_KEY
npm run token                      # prints a random path token
npx wrangler secret put MCP_PATH_TOKEN

npm run deploy

After deploying, note the workers.dev URL that wrangler prints. Verify the gate:

curl -i https://hevy-mcp.<your-subdomain>.workers.dev/            # expect 404
curl -i -X POST https://hevy-mcp.<your-subdomain>.workers.dev/mcp/<token> \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

The second call should return a serverInfo block naming hevy-mcp.

Connect it to Claude

1. In Claude, open Settings > Connectors > Add custom connector.

2. Name it Hevy and paste https://hevy-mcp.<your-subdomain>.workers.dev/mcp/<token> as the URL.

3. Leave authentication empty. The token in the path is the credential.

4. Start a chat, enable the connector, and ask for your last three workouts. Compare against the app.

5. Test a write by asking Claude to create a throwaway routine, confirm it appears in Hevy, then delete it in the app.

Treat the full URL like a password. If it leaks, run npm run token, set the new value with wrangler secret put MCP_PATH_TOKEN, redeploy, and update the connector.

Local development

cp .dev.vars.example .dev.vars   # fill in real values; the file is gitignored
npm run dev                      # http://127.0.0.1:8787/mcp/<token>
npm run check                    # typecheck + wrangler dry-run build

Project layout

src/index.ts     Worker entry, token gate, McpServer factory and all tool definitions
src/hevy.ts      fetch wrapper for api.hevyapp.com/v1 with typed errors
wrangler.toml    Worker config (nodejs_compat, no bindings)

Design notes

• Built on createMcpHandler from the agents package rather than McpAgent. The latter is now marked deprecated and feature-frozen upstream, and it needed a Durable Object that a read-mostly proxy never used.

• The first deployment of this Worker did use a Durable Object class. wrangler.toml carries a deleted_classes migration so redeploying cleans it up. On a brand new Worker the two migrations cancel out.

• Write tools stay limited to routines until reads have been trusted for a while. Adding workout or body-measurement writes is a matter of registering more tools against endpoints that already exist in the Hevy spec.