hevy-mcp: an MCP server that puts a Hevy PRO training log inside Claude, Cursor or Codex
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.
At a glance
- What is it?
- hevy-mcp exposes 22 MCP tools over the Hevy API so an assistant can read, analyse and write workouts, routines, folders, exercise templates and body measurements. The design is heavier than most MCP servers, and the Hevy PRO API key requirement is the first thing to check.
- Who is it for?
- Adopt hevy-mcp if you already pay for Hevy PRO, your training log lives in Hevy, and you want an assistant to answer questions across weeks of workouts or write sessions back into the app. Do not adopt it if you are not on Hevy PRO, since the README states an API key from that tier is required, or if you want deletion, which the CLI explicitly does not support.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap hevy-mcp fills between a training log and a chat window
Hevy keeps workouts, routines, routine folders, exercise templates and body measurements behind its own app and API. An assistant has no way to read that data unless something translates the API into tool calls the model can invoke. That translation layer is what hevy-mcp is. The README frames it as a Model Context Protocol server that lets assistants read, analyze, create, and update Hevy resources through authenticated API requests. The audience is narrow and specific: people who already track training in Hevy and already use an MCP-capable client such as Claude, Cursor or Codex. The README states plainly that a Hevy API key, available with Hevy PRO, is required. That single sentence rules out free-tier Hevy users before any installation step. The payoff described in the README is analysis that would otherwise mean scrolling: summarising one to twelve weeks of workouts and body measurements in one tool call, finding frequently trained exercises or consistency gaps, and creating a completed workout from a saved routine after asking for missing set results.
A monorepo with six packages and three runtime scopes
The repository is a private workspace, not a single published file. `@hevy-mcp/hevy-client` owns the web-safe Hevy client. `@hevy-mcp/operations` owns reusable Hevy domain operations. `@hevy-mcp/core` owns the MCP tools and server construction. `hevy-mcp` is the published Node.js stdio adapter. `@hevy-mcp/worker` is a private Cloudflare HTTP and OAuth adapter. `@chrisdoc/hevy-cli` is a standalone CLI. Only Node and CLI are public packages, so the internal boundaries are a maintenance choice rather than something consumers install directly. The interesting part is the request runtime. The public `HevyClient` stays Promise-based, while `@hevy-mcp/operations` provides Effect-first programs for reads, mutations and composite workflows. The README says Effect is the control structure, not a delay calculator: `@hevy-mcp/hevy-client` owns retry schedules, per-attempt timeouts and interruption. MCP tools and CLI commands collapse each invocation once at their Promise adapter boundary, which means callers do not have to write Effect code to use the public surface. Three nested scopes govern lifetime: process scope for telemetry, signal handlers and transport shutdown; server scope for the MCP runtime and the exercise-template cache; request scope for each invocation's deadline and MCP request signal, so fiber interruption reaches the Hevy request.
Connecting through the hosted endpoint or running the server locally
There are two paths. The hosted route avoids installing anything: the README points Claude users to Settings, then Connectors, then Add custom connector, with the URL `https://mcp.hevy-mcp.dev/mcp`. You complete an OAuth flow and enter the Hevy API key when prompted. The repository also includes a Claude plugin that connects to that OAuth endpoint without embedding the user's Hevy API key. The local route uses `npx`, `bunx` or the official Docker image, and the README says Codex, Claude Desktop, Cursor and other MCP clients are supported. For terminal use there is a separate package, `@chrisdoc/hevy-cli`, installed with `npm install -g @chrisdoc/hevy-cli`, then `export HEVY_API_KEY=your-hevy-api-key`. Two documented commands are `hevy workouts list --page-size 10` and `hevy summary --weeks 4`. Adding `--json` to any command makes output suitable for scripts and pipelines. The README is explicit that the CLI is a standalone Hevy API client, not an MCP wrapper, and that deletion is not supported. The CLI README under `packages/cli/README.md` is where the full command reference, pagination behaviour and exit codes live.
Where the design gets awkward, and where it is the wrong tool
The Effect layer is the first trade-off to weigh. Retry schedules, per-attempt timeouts and interruption tied to the MCP request signal are real behaviour, and the README is careful to say the Promise façades are unchanged. But contributors still meet two mental models in one repository: Promise-based public methods and Effect programs underneath. The README also notes the Worker adapter is not Effect-wide, since its OAuth, bindings and request handling remain platform-specific Promise code, with only the validation-cache retry Effect-controlled. That is a deliberate boundary, and it is also a seam a reader has to hold in their head. The second constraint is coverage. Deletion is not supported by the CLI, so any workflow that assumes full lifecycle management over Hevy data is out of scope. Third, the tool surface is capped: the README states the MCP catalog remains 22 tools, which means the assistant can only do what those tools expose. If your question needs a slice of Hevy data outside workouts, routines, folders, exercise templates and body measurements, this server will not reach it. Finally, the hosted Cloudflare endpoint puts your Hevy API key and training data through a third party's Worker. The README does not describe the Worker's data handling, so that is a question to answer before choosing the hosted route over local stdio.
How it compares with calling the Hevy API yourself
The alternative is a script or a small service that talks to the Hevy API directly. The difference is where the translation work sits. A hand-written client gives you exactly the endpoints and response shapes you choose, and nothing else runs between your code and Hevy. hevy-mcp instead gives you a fixed catalog of 22 tools with Zod input and response contracts, plus retry and timeout behaviour already wired into the request path, plus a cache of exercise templates held at server scope and finalised when the server closes. You trade flexibility for a defined surface that an MCP client can discover and call. The CLI sits between the two: `@chrisdoc/hevy-cli` reads workouts, routines, exercises and body measurements from the Hevy API and can create or update them with explicit confirmation, with `--json` for pipelines. It is a standalone API client, so it is the better fit when the consumer is a shell script rather than a language model. Choosing between them comes down to whether the caller is an assistant that needs tool discovery or a script that needs deterministic output.
What to check before pointing an assistant at your training log
Confirm the Hevy PRO requirement applies to you, because nothing else in the setup matters without an API key. Decide between the hosted connector and a local run: the hosted endpoint is one URL and an OAuth prompt, while local stdio with `npx`, `bunx` or Docker keeps the key on your machine. Read `packages/cli/README.md` if the CLI is your entry point, since pagination behaviour and exit codes are documented there rather than in the main README. Check the version you install against the release list, which shows `hevy-mcp@6.1.11` and `@chrisdoc/hevy-cli@1.2.10` published on the same day, with `hevy-mcp@6.1.9` a few days earlier. The README states that generated Kubb API functions and `.kubb` internals are not public API, so anything built against those will break without warning. The project is MIT licensed, which permits commercial and private use and modification, but the licence text in `./LICENSE` is the authority on terms and this article is not legal advice. The README does not document a migration path between major versions, so pinning a version is the safer default for anything you depend on.
Editorial conclusion
Adopt hevy-mcp if you already pay for Hevy PRO, your training log lives in Hevy, and you want an assistant to answer questions across weeks of workouts or write sessions back into the app. Do not adopt it if you are not on Hevy PRO, since the README states an API key from that tier is required, or if you want deletion, which the CLI explicitly does not support. Before wiring it into a client, verify two things: that the OAuth connector at mcp.hevy-mcp.dev/mcp completes against your Hevy account, and that the tool you plan to call exists in the 22-tool catalog at the version you install.
Community notes