Hevy MCP

@diecoscai/hevy-mcp

Model Context Protocol server for the Hevy fitness API. Manage workouts, routines, exercises, and body measurements from any MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code, and anything else that speaks MCP over stdio.

Overview

This MCP server exposes the public Hevy API (api.hevyapp.com/v1) as 22 strongly-typed tools. LLM agents can list workouts, create routines, look up exercise templates, track body measurements, and follow a delta-sync feed — all without bespoke glue code on the client.

Design goals:

• Safe by default. Write operations return a { dry_run: true, would_send: { ... } } preview unless HEVY_MCP_ALLOW_WRITES=1 is set. The Hevy API has no DELETE on any resource, so accidental writes are permanent; dry-run is the brake.
• Validated at the edge. Every tool input is checked with Zod before a single byte crosses the network. Oversized titles, unknown fields, out-of-range page sizes, and invalid enums fail fast with SEP-1303-shaped errors the model can self-correct.
• Zero extra setup. Authentication is a single environment variable — HEVY_API_KEY. No wizards, no config files; just paste the snippet for your client.

Schemas are generated from Hevy's own OpenAPI spec and re-synced automatically, so the server adapts to upstream changes instead of drifting. Writes are dry-run by default; every public endpoint is covered.

Project status

Maintenance mode. Feature-complete for Hevy's public API. Schemas are generated from Hevy's OpenAPI spec; a scheduled workflow re-syncs them weekly and opens a PR on any change, and a live integration run catches undocumented server changes. Bug reports and PRs welcome via the issue tracker.

Prerequisites

• Node.js 20 or later (node --version).
• A Hevy Pro subscription — the public API is a Pro feature.
• A Hevy API key from https://hevy.com/settings?developer.

Quick setup

The fastest path is the setup subcommand — it validates your key and writes a config file the server picks up automatically:

npx @diecoscai/hevy-mcp setup

It prompts for your Hevy Pro API key (from https://hevy.com/settings?developer), checks it against the live API, asks whether to enable write operations, and saves everything to ~/.config/hevy-mcp/config.json (mode 0600). Then add the server to your MCP client with no env block needed:

{

"mcpServers": { "hevy": { "command": "npx", "args": ["-y", "@diecoscai/hevy-mcp"] } } }

Restart the client — the 22 Hevy tools appear in the tools panel.

Prefer environment variables? Skip setup and pass HEVY_API_KEY (and optionally HEVY_MCP_ALLOW_WRITES=1) in the env block instead — see Configuration. Env vars always take precedence over the config file.

Note on bare invocation. Running npx @diecoscai/hevy-mcp with no arguments starts a stdio MCP server and blocks, waiting for an MCP client to connect over its stdin/stdout. You don't run it in a terminal yourself — your MCP client spawns it. Use npx @diecoscai/hevy-mcp --help, --version, or setup for a non-blocking invocation.

Write tools are dry-run by default. The first time you ask the server to create or update anything (a workout, a routine, a body measurement) you'll see a preview payload, not a real change. Enable writes by answering "yes" during setup, or by setting HEVY_MCP_ALLOW_WRITES=1 in the env block — see Safety.

Run from source

You can also run the server directly from a local clone instead of via npx. Useful if you want to pin a specific commit, debug a tool locally, or run an unreleased version. Contributors should use Development below instead.

git clone https://github.com/diecoscai/hevy-mcp.git

cd hevy-mcp npm ci npm run build

Then point your MCP client at the built entry instead of npx @diecoscai/hevy-mcp:

{

"mcpServers": { "hevy": { "command": "node", "args": ["/absolute/path/to/hevy-mcp/dist/index.js"], "env": { "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE" } } } }

The env block (including HEVY_MCP_ALLOW_WRITES) works identically to the npx snippets below.

Configuration

Each MCP client spawns the server as a stdio subprocess with HEVY_API_KEY in its env block.

Claude Desktop

Config path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json *(Anthropic does not ship an official Linux build of Claude Desktop as of 2026; the path applies only to unofficial community builds.)*

{

"mcpServers": { "hevy": { "command": "npx", "args": ["-y", "@diecoscai/hevy-mcp"], "env": { "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE" } } } }

Add "HEVY_MCP_ALLOW_WRITES": "1" to the env block to enable write tools.

Claude Code CLI

claude mcp add hevy --env HEVY_API_KEY=PASTE_YOUR_KEY_HERE -- npx -y @diecoscai/hevy-mcp

To enable writes, append --env HEVY_MCP_ALLOW_WRITES=1.

Cursor

Config path: ~/.cursor/mcp.json. Same shape as Claude Desktop:

{

"mcpServers": { "hevy": { "command": "npx", "args": ["-y", "@diecoscai/hevy-mcp"], "env": { "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE" } } } }

VS Code (native MCP support, 1.102+)

Create .vscode/mcp.json at the root of your workspace (or put the same shape under a user-level MCP config if your VS Code build supports one):

{

"servers": { "hevy": { "command": "npx", "args": ["-y", "@diecoscai/hevy-mcp"], "env": { "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE" } } } }

If you use a third-party MCP extension that expects a different shape, check its docs — VS Code's native MCP integration landed in 1.102.

See docs/configuration.md for troubleshooting and client-specific notes, and docs/examples.md for end-to-end flows you can run with a connected MCP client.

Safety — dry-run writes

Every POST and PUT tool handler checks HEVY_MCP_ALLOW_WRITES at call time:

• Unset (default) — the tool returns a preview instead of making the HTTP call:

  {

"dry_run": true, "would_send": { "method": "POST", "path": "/v1/routine_folders", "body": { "routine_folder": { "title": "Push days" } } }, "hint": "set HEVY_MCP_ALLOW_WRITES=1 to execute" }

• Set to 1 — the tool performs the real request.

The Hevy API has no `DELETE` endpoint on any resource. A bad write cannot be rolled back from the client — it will persist on your account until you manually fix it in the Hevy app. Dry-run is the first line of defence; explicit opt-in for writes is the second.

Tool reference (summary)

The server exposes 23 tools grouped by resource. See docs/tools.md for input schemas and examples.

User

Workouts

Routines

Routine folders

Exercise templates

Body measurements

Environment variables

\* HEVY_API_KEY is required *unless* you ran npx @diecoscai/hevy-mcp setup, which saves the key (and the writes setting) to ~/.config/hevy-mcp/config.json. Resolution order: the env var wins; the config file is the fallback. The same precedence applies to HEVY_MCP_ALLOW_WRITES vs the file's allowWrites.

Exercise-template cache

hevy_list_exercise_templates and hevy_get_exercise_template read through a per-process in-memory cache (Map with per-entry TTL, default 1 hour). The template catalog is large and near-static within a session, so repeated resolution — e.g. looking up an id while building a routine — costs one HTTP round-trip instead of many.

hevy_create_exercise_template invalidates the list portion of the cache on a successful write; singleton template entries are left alone (they can't be made stale by creating a different custom template). The cache is never persisted across processes.

Disable the cache entirely with HEVY_MCP_DISABLE_CACHE=1, or shorten / lengthen its lifetime with HEVY_MCP_CACHE_TTL_SECONDS.

Webhooks — intentionally not exposed

Hevy's public API (api.hevyapp.com/v1/*) does not document webhook subscriptions; the releva