Hevy Coach MCP

The problem: giving the assistant reliable context

Workouts, routines and measurements live in Hevy. Analysing them in a conversation requires connecting that history and turning it into comparable information. I built an MCP server that queries the Hevy API and calculates progress, volume and consistency metrics.

The decision: query and calculate before interpreting

The server retrieves live data and performs the calculations; the MCP client receives the results to compose a response. This separation makes the distinction between a calculated metric and the assistant’s interpretation explicit.

• Hevy API: workouts, routines, exercises and measurements.
• MCP server: query, calculation and write tools with separate responsibilities.
• Compatible client: conversation, interpretation and authorisation controls.

There is no local cache or workout database, avoiding a second copy that needs synchronisation. The trade-off is depending on the API’s availability, latency and limits for every query.

Write boundaries are part of the design

The project can create and update routines, create folders and log body measurements. It does not write to workout history, which is the basis of its calculations.

Tools carry read or write annotations for the MCP client. These help the client decide when to ask for confirmation; they are not, by themselves, a server-enforced guarantee of consent.

Hevy API keys do not offer granular permissions. It is therefore important to distinguish what the credential allows from the operations this server exposes.

Designing for a write that cannot be undone

An HTTP error does not always mean an operation did not happen. If a creation reaches Hevy but the response fails, repeating it can create a duplicate. The integration has no delete operation to compensate for this. That constraint changes how writes are prepared and executed.

• Resolve before sending. When creating a routine, all exercise names are resolved first. If one is unknown or ambiguous, the tool returns the problem without sending an incomplete routine.
• Retry according to the operation. The client allows bounded retries for 5xx responses on reads, but not on writes. It handles 429 responses separately. Returning an error is preferable to risking a duplicate creation.
• Read before updating. When the API replaces an entire record, omitting fields can erase them. The tool retrieves the existing state: it preserves unspecified measurements and, when renaming a routine, its exercises’ rest times and rep ranges. Explicitly replacing the exercises remains a destructive operation.

These are defences against specific failures, not a distributed transaction or an exactly-once execution guarantee. A concurrent modification between the read and the write remains a limitation of this approach.

Missing data does not mean zero progress

The calculation engine receives data and returns results without calling the API. This makes it possible to check formulas against known inputs and keep interpretation separate from arithmetic. To estimate one-rep max, sets without valid weight or reps are excluded; if no set qualifies, the result is null. A single bodyweight measurement does not become a trend either.

Filling these gaps with zeros would produce a seemingly more complete answer, but would confuse missing information with a measured result. The assistant must be able to say it has insufficient data.

The public tests cover ambiguous names that produce no writes, field preservation during updates, failed creations that are not retried, and sets that cannot be scored. They check server rules with controlled data; they do not, by themselves, demonstrate Hevy’s availability or the quality of a model’s responses.

One way to try it

With a Hevy PRO account and an API key configured in a compatible client, you can start by checking the connection and comparing two periods:

Check the connection to Hevy. Compare workout count and volume over the last four weeks with the previous four. Explain which data you used and what you cannot conclude. 

This is a suggested query, not a screenshot of an actual result. The repository includes connection instructions, available tools and their limitations.

What this project demonstrates

An integration between an external API and AI clients, with calculations separated from conversation and a defined write scope. The verifiable outcome is the code and its public documentation; no unmeasured adoption figures or training improvements are claimed.

Public code and tests reviewed on 27 September 2026. Technical links point to commit c3a2326 so the decisions described remain verifiable.