Remote MCP server connecting Claude to the Hevy workout API — log workouts, build routines, track goals, and get AI coaching on web and mobile. Deployed free on Cloudflare Workers.
Hevy MCP Server
A remote MCP server that connects Claude (web and mobile) to the Hevy workout tracker API. Deployed on Cloudflare Workers — no VPS, no monthly cost.
Requirements
- Cloudflare account (free)
- Hevy PRO account + API key from https://hevy.com/settings?developer
- Node.js 18+
Setup
1. Install dependencies
npm install --ignore-scripts
--ignore-scriptsskips a native image library (sharp) pulled in by Wrangler's local simulator. It's not needed for deployment.
2. Log in to Cloudflare
npx wrangler login
3. Store your secrets
Hevy API key (get it at https://hevy.com/settings?developer):
npx wrangler secret put HEVY_API_KEY
MCP secret token (guards the server URL — generate a random string):
openssl rand -hex 16 | pbcopy # copies a token to your clipboard
npx wrangler secret put MCP_SECRET
Both are stored encrypted on Cloudflare — never in the code.
4. Deploy
npx wrangler deploy
Your server will be live at:
https://hevy-mcp.<your-subdomain>.workers.dev
5. Connect to Claude
- Go to claude.ai (web browser — required for initial setup)
- Settings → Connectors → Add custom connector
- Name:
Hevy - URL:
https://hevy-mcp.<your-subdomain>.workers.dev/sse/<your-MCP_SECRET> - Save
Once added on the web, the connector is also available in Claude Mobile.
Local development
cp dev.vars.example .dev.vars # add your API key to .dev.vars
npx wrangler dev # runs at http://localhost:8787
Updating
Edit src/index.ts, then redeploy:
npx wrangler deploy
The Claude connector URL never changes — no need to reconfigure it.
Tools
Workouts
| Tool | Description |
|------|-------------|
| list_workouts | Paginated list of logged workouts, newest first |
| get_workout | Full details of a single workout by ID |
| get_workout_count | Total number of workouts logged |
| log_workout | Log a completed workout with exercises and sets |
Routines
| Tool | Description |
|------|-------------|
| list_routines | Paginated list of saved workout routines |
| get_routine | Full details of a single routine by ID |
| create_routine | Create a new routine with exercises and sets |
| update_routine | Edit an existing routine (replaces all exercises/sets) |
Exercise Templates
| Tool | Description |
|------|-------------|
| list_exercise_templates | Browse all exercise templates (use to find template IDs) |
| get_exercise_template | Details of a single exercise template by ID |
Routine Folders
| Tool | Description |
|------|-------------|
| list_routine_folders | List routine folders |
| create_routine_folder | Create a new routine folder |
Profile
| Tool | Description |
|------|-------------|
| get_profile | Retrieve stored user profile (age, weight, experience, injuries, etc.) |
| update_profile | Update profile fields — only provided fields are changed |
Goals
| Tool | Description |
|------|-------------|
| list_goals | List all training goals |
| set_goal | Add a new goal (exercise, target, optional deadline) |
| delete_goal | Remove a goal by ID |
Profile fields
The profile is stored persistently in the Durable Object's SQLite database and survives redeployments.
| Field | Type | Example |
|-------|------|---------|
| name | string | "Liggar" |
| age | number | 28 |
| gender | string | "male" |
| weight_kg | number | 80 |
| height_cm | number | 178 |
| experience_level | beginner | intermediate | advanced | "intermediate" |
| injuries | string | "left shoulder impingement" |
| available_days_per_week | number | 4 |
| session_duration_minutes | number | 60 |
| preferred_language | string | "English" |
| notes | string | "prefer dumbbells over machines" |
Example prompts
Set up my profile: 26 years old, 75kg, 175cm, intermediate, training 4 days a week.
Based on my last 3 Pull Day workouts, am I progressing on Bent Over Row?
My goal is Bench Press 3x8 @ 70kg by end of June. Am I on track?
Create a Push/Pull/Legs routine based on the exercises I use most.
Log today's workout: Push Day, 9:00–10:05 AM, Bench Press 4x35kg, Shoulder Press 3x14kg.
Security
The server is protected by a secret token embedded in the URL path. Any request without the correct token returns a plain 404 — the same response as any unknown path, so it doesn't reveal the server exists.
The token is stored as a Cloudflare encrypted secret (MCP_SECRET) and never appears in the source code. Keep your connector URL private — it is effectively the password to your Hevy data.
Project structure
hevy-mcp/
├── src/
│ └── index.ts # MCP server — all tools defined here
├── wrangler.jsonc # Cloudflare Workers config
├── tsconfig.json # TypeScript config
├── package.json
└── dev.vars.example # Template for local development secrets