chrisdoc/hevy-mcp

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

Hevy MCP – an AI‑friendly bridge to the Hevy fitness app

What it is – hevy-mcp is a small open‑source server that implements the Model Context Protocol (MCP). It exposes the Hevy workout‑tracking API (read‑only and write‑capable endpoints) as a set of MCP tools that AI assistants such as Claude, Codex, Cursor, or any other MCP‑compatible client can call.

Why it matters – By turning personal workout data into a standard tool interface, the server lets large‑language‑model assistants reason about your training history, answer natural‑language questions, and even create or update workouts, routines, custom exercises, and body‑measurement records – all under the user’s explicit consent.

Core capabilities (23 tools)

Category	Example tools	What you can do
Training analysis	`get-training-summary`, `analyze-workout-progress` (guided prompt)	Summarize weeks of workouts and body‑measurements, spot gaps, show most‑frequent exercises.
Workouts	`get-workouts`, `get-workout`, `create-workout`, `update-workout`, `replace-workout-exercises`, `get-workout-events`	List past sessions, fetch a single workout’s details, log a new completed workout, edit metadata or exercise sets.
Routines & folders	`search-routines`, `get-routines`, `get-routine`, `create-routine`, `update-routine`, `create-routine-folder`, `get-routine-folder`	Discover saved routines, read a routine’s layout, create new reusable routines or organise them in folders.
Exercise catalog	`search-exercise-templates`, `get-exercise-template`, `create-exercise-template`, `get-exercise-history`	Browse Hevy’s full exercise library, add custom templates, retrieve past performed sets for a given exercise.
Body measurements	`get-body-measurements`, `get-body-measurement`, `create-body-measurement`, `update-body-measurement`	Track weight, body‑fat, etc.; add or correct entries.
Diagnostics	`feedback`	Send a short privacy‑safe report if something goes wrong.

All mutation tools are flagged for MCP confirmation, so a compatible client will ask you before any data‑changing operation.

How it works

AI assistant → MCP (streamable HTTP or stdio) → hevy‑mcp server → Hevy API

Hosted mode – a Cloudflare Worker runs the server at https://mcp.hevy-mcp.dev/mcp. Clients send a fixed Authorization: Bearer <Hevy‑API‑key> header; the worker validates the key, caches it for 15 min, and forwards it to Hevy.
Local mode – run the npm package (or Docker image) on your own machine. The server reads the API key from the HEVY_API_KEY environment variable and communicates over stdio with the client.
OAuth layer – the hosted worker also offers an optional OAuth 2.1 flow (used by Claude.ai custom connectors) that stores the key encrypted in a grant, so clients that cannot set static headers can still authenticate.

Getting started (quickest path)

Obtain a Hevy API key – requires a Hevy PRO subscription (Settings → Developer → API key).
Connect – use the public endpoint https://mcp.hevy-mcp.dev/mcp.
- For Codex: set HEVY_API_KEY in your environment and add the server with codex mcp add hevy --url https://mcp.hevy-mcp.dev/mcp --bearer-token-env-var HEVY_API_KEY.
- For other clients, supply the same URL and a fixed Authorization: Bearer <key> header.
Ask a question – e.g., “Give me a training summary for the last four weeks.” The assistant will invoke get-training-summary and return a concise report.

If you prefer full control, you can run the server locally:

npm install -g hevy-mcp   # or use npx/bunx/docker
export HEVY_API_KEY=your-key
npx -y hevy-mcp            # starts stdio MCP server

Configure your client to launch that command (see the README for Claude Desktop, Cursor, Google Antigravity, etc.).

Ecosystem & tooling

@chrisdoc/hevy-cli – a separate command‑line client that talks directly to the Hevy API (no MCP). Useful for scripting or quick data dumps.
Claude plugin – .claude-plugin/plugin.json and .mcp.json let Claude.ai connect to the hosted endpoint via OAuth, exposing a Hevy workout skill.
Docker image – ghcr.io/chrisdoc/hevy-mcp:latest (supports linux/amd64 and linux/arm64).
MCP toplist badge – shows the server’s ranking among public MCP implementations.

Who might use it

Fitness‑focused AI assistants – let a personal LLM coach analyse your progress, suggest routine tweaks, or log a workout you just completed.
Developers building custom agents – use the 23 ready‑made tools instead of hand‑crafting Hevy API calls.
Power users – combine the hevy-mcp server with other MCP services (e.g., a nutrition tracker) to build a unified health‑assistant.

License & contribution

Licensed under MIT.
Contributions are welcome; see CONTRIBUTING.md for details on self‑hosting the Cloudflare Worker, adding new tools, or improving documentation.

Bottom line: hevy-mcp turns your personal Hevy workout data into a clean, AI‑ready interface, enabling natural‑language queries and safe, confirmed mutations from any MCP‑compatible assistant.