@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

| Tool | Description | | --- | --- | | hevy_get_user_info | Return the authenticated user (name, id, profile URL). |

Workouts

| Tool | Description | | --- | --- | | hevy_list_workouts | Paginated workouts (pageSize 1-10). | | hevy_get_workout | Fetch one workout by UUID. | | hevy_get_workout_count | Total number of workouts on the account. | | hevy_get_workout_events | Delta-sync feed: updated / deleted events since a timestamp. | | hevy_create_workout | Log a new workout (write — dry-run default). | | hevy_update_workout | Full replace of an existing workout (write — dry-run default). |

Routines

| Tool | Description | | --- | --- | | hevy_list_routines | Paginated routines. | | hevy_get_routine | Fetch one routine by UUID. | | hevy_create_routine | Create a routine (write — dry-run default). | | hevy_update_routine | Full replace of a routine (write — dry-run default). |

Routine folders

| Tool | Description | | --- | --- | | hevy_list_routine_folders | Paginated folders. | | hevy_get_routine_folder | Fetch one folder by positive integer id. | | hevy_create_routine_folder | Create a folder (write — dry-run default). |

Exercise templates

| Tool | Description | | --- | --- | | hevy_list_exercise_templates | Paginated exercise library — the only list that accepts pageSize up to 100. | | hevy_search_exercise_templates | Search templates by name (case-insensitive substring). Resolves a human name (e.g. "bench press") to an exercise_template_id. Paginates the full catalog; results cached for an hour. | | hevy_get_exercise_template | Fetch one template by id (8-char hex for built-ins, UUID for custom). | | hevy_create_exercise_template | Create a custom exercise (write — dry-run default). | | hevy_get_exercise_history | All logged sets for a given exercise template. |

Body measurements

| Tool | Description | | --- | --- | | hevy_list_body_measurements | Paginated measurements. Records are keyed by date. | | hevy_get_body_measurement | Fetch the record for a single YYYY-MM-DD. | | hevy_create_body_measurement | Create a new record (write — dry-run default). 409 if the date already exists. | | hevy_update_body_measurement | Replace the record for a date — any field not sent is set to NULL (write — dry-run default). |

Environment variables

| Name | Required | Description | | --- | --- | --- | | HEVY_API_KEY | required* | Hevy Pro API key (UUID v4). Typically passed through the env block of your MCP client config. | | HEVY_MCP_ALLOW_WRITES | optional | Set to 1 to enable real POST / PUT calls. Any other value (including unset) keeps dry-run on. | | HEVY_MCP_DISABLE_CACHE | optional | Set to 1 to disable the in-memory exercise-template cache (see below). | | HEVY_MCP_CACHE_TTL_SECONDS | optional | Cache TTL in seconds. Default 3600. Ignored when the cache is disabled. |

* 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 relevant endpoints live on the private web-session API (/webhook-subscription, /subscribe_to_webhook) which uses a different auth scheme (refresh-token bearer, not the api-key header this server uses). Exposing tools for them would either (a) ship handlers that throw "endpoint not available" to every user, or (b) force users to hand over a web session token just to register a URL.

If you need incremental sync, use hevy_get_workout_events with a since timestamp — it covers both updated and deleted workouts and is the only mechanism the public API offers for change detection.

If Hevy publishes webhooks in the public OpenAPI spec, subscription tools will land here with the same dry-run gate as the other writes.

Some other Hevy MCP servers expose webhook tools by reaching Hevy's private web-session API. This server deliberately stays on the documented public API.

Spec ≠ reality

The public OpenAPI doc (self-versioned 0.0.1) diverges from the live server in several places — wrong wrapper for POST /v1/exercise_templates, wrong enum values for CustomExerciseType, folder_id rejected on PUT /v1/routines/{id}, plain-text response on a successful template create, and more. This server implements what the real server accepts. The full list of confirmed divergences lives in docs/api-quirks.md and can be re-verified with the scripts/verify-api.sh probe suite (lives in the GitHub repo, not in the npm tarball).

Development

For contributors working on the server itself. If you only want to run the server locally against your own Hevy account, use Run from source instead.

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build
npm test

Useful scripts:

| Script | Purpose | | --- | --- | | npm run dev | tsc --watch for the source. | | npm run lint | Biome lint across src/ + tests/. | | npm run format | Biome auto-format. | | npm run check | Biome combined lint + format check. | | npm run coverage | Vitest with V8 coverage. | | npm run smoke | End-to-end: npm ci && build && test && lint + stdio probe + language gate. | | npm run inspect | Launches the MCP Inspector against the built server. |

Adding a tool:

1. Add a Zod schema in src/validate.ts (.strict() on every object).
2. Add the tool spec (name, description, JSON Schema inputSchema) to the TOOLS array in src/index.ts.
3. Add a case in the dispatch switch; always call validateInput(name, rawArgs) before touching the network; wrap writes with guardWrite.
4. Extend tests under tests/ (schema + negative probes at minimum).
5. Update the table in this README.

See CONTRIBUTING.md for more.

Security

• API keys live in your MCP client's config file (same threat model as any other key you'd paste there). The server never reads or writes a config file of its own.
• Writes are dry-run by default; rotating a leaked key in the Hevy app and pasting the new one into your client config takes under a minute.
• The server only ever calls documented /v1/* endpoints — no private API traffic, no telemetry, no third-party fan-out.

See docs/security.md for the full threat model.

Contributing

Contributions welcome. Please read CONTRIBUTING.md before opening a PR.

License

MIT.

Links

• Hevy public API docs — https://api.hevyapp.com/docs
• MCP registry entry — https://registry.modelcontextprotocol.io/v0/servers?search=io.github.diecoscai/hevy-mcp (populated after publish)
• Issue tracker — https://github.com/diecoscai/hevy-mcp/issues
• MCP spec — https://modelcontextprotocol.io