Skip to main content
Glama
@diecoscai/hevy-mcp

@diecoscai/hevy-mcp

by diecoscai

@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.

npm version CI license node

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.

Related MCP server: Hevy MCP

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

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.

Available Tools

23 tools
hevy_create_body_measurementA

Create one body-measurements record (POST /v1/body_measurements). Required: date (YYYY-MM-DD). All metric fields are optional and nullable: weight_kg, lean_mass_kg, fat_percent, neck_cm, shoulder_cm, chest_cm, left_bicep_cm, right_bicep_cm, left_forearm_cm, right_forearm_cm, abdomen, waist, hips, left_thigh, right_thigh, left_calf, right_calf. If a record already exists for that date, the server returns 409 — use hevy_update_body_measurement instead. Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: date (required), hips, waist, abdomen, +14 more.

hevy_create_exercise_templateA

Create a custom exercise template (POST /v1/exercise_templates). Required: title, exercise_type, muscle_group, equipment_category. exercise_type enum (8): weight_reps, reps_only, bodyweight_reps, bodyweight_assisted_reps, duration, weight_duration, distance_duration, short_distance_weight. muscle_group enum (20): abdominals, shoulders, biceps, triceps, forearms, quadriceps, hamstrings, calves, glutes, abductors, adductors, lats, upper_back, traps, lower_back, chest, cardio, neck, full_body, other. equipment_category enum (9): none, barbell, dumbbell, kettlebell, machine, plate, resistance_band, suspension, other. other_muscles is an optional array of muscle_group values. Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: exercise (required).

hevy_create_routineA

Create a routine (POST /v1/routines). Required: title, exercises[]. Each exercise needs an exercise_template_id — call hevy_list_exercise_templates to find it. Optional folder_id (positive integer) places the routine in a folder (use hevy_list_routine_folders to discover folder ids). Set types: warmup|normal|failure|dropset. rep_range { start, end } is accepted on routine sets (NOT on workout sets). Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: routine (required).

hevy_create_routine_folderA

Create a routine folder (POST /v1/routine_folders). Takes only title. The new folder is inserted at index 0; existing folders shift down by one. There is no update or delete tool for folders — once created, the title is fixed. Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: title (required).

hevy_create_workoutA

Create a workout (POST /v1/workouts). Required: title, start_time (ISO-8601), end_time (ISO-8601), exercises[]. Each exercise needs an exercise_template_id — call hevy_search_exercise_templates to resolve it from a name, or hevy_get_exercise_template if you already know the id. Set types: warmup|normal|failure|dropset. RPE is null or one of 6, 7, 7.5, 8, 8.5, 9, 9.5, 10. Superset ids must be contiguous across adjacent exercises. rep_range is routines-only and is rejected here. Dry-run by default: returns { dry_run: true, executed: false, ... } unless the env var HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: workout (required).

hevy_get_body_measurementA

Fetch one body-measurements record by date (GET /v1/body_measurements/{date}). Returns 404 if no record exists for that date.

Inputs: date (required).

hevy_get_exercise_historyA

List every logged set for the given exercise template (one row per set, includes warmups/dropsets/failures). Two filter modes, combinable: pagination via page (1-indexed) and pageSize (1-10), and date-range filtering via start_date / end_date (ISO-8601 datetimes). Without start_date/end_date, results span all time, newest-first.

Inputs: exerciseTemplateId (required), page, end_date, pageSize, +1 more.

hevy_get_exercise_templateA

Fetch one exercise template by id. Accepts both 8-char uppercase hex (built-in) and lowercase UUID (custom).

Inputs: exerciseTemplateId (required).

hevy_get_routineC

Fetch one routine by UUID.

Inputs: routineId (required).

hevy_get_routine_folderB

Fetch one routine folder by its positive integer id.

Inputs: folderId (required).

hevy_get_user_infoA

Return the authenticated user (name, id, profile URL). Reads GET /v1/user/info. Requires a Hevy Pro api-key.

Inputs: no named parameters.

hevy_get_workoutA

Fetch one workout by UUID. Returns the full record including exercises and sets.

Inputs: workoutId (required).

hevy_get_workout_countA

Return { workout_count }: the total number of workouts on the account.

Inputs: no named parameters.

hevy_get_workout_eventsA

Delta sync feed: events newer than since (ISO-8601). Each event is either { type: "updated", workout } or { type: "deleted", id, deleted_at }. To incrementally sync a local cache: on first call pass since=1970-01-01T00:00:00Z, then for each subsequent call pass the timestamp of the newest event you have seen. This is the ONLY way to detect deletions — the Hevy API has no DELETE endpoint, so deleted workouts surface here and nowhere else. pageSize 1-10.

Inputs: page, since, pageSize.

hevy_list_body_measurementsA

List body measurements (GET /v1/body_measurements). Envelope: { page, page_count, body_measurements }. pageSize 1-10. Records are keyed by date (YYYY-MM-DD), not by id. No DELETE endpoint exists.

Inputs: page, pageSize.

hevy_list_exercise_templatesA

List exercise templates (built-in + custom). Envelope: { page, page_count, exercise_templates }. pageSize is 1-100 — this is the ONE endpoint with a larger cap; every other list is capped at 10. Built-in ids are 8-char uppercase hex; custom ids are lowercase UUIDs.

Inputs: page, pageSize.

hevy_list_routine_foldersB

List routine folders. pageSize 1-10. Envelope: { page, page_count, routine_folders }. No DELETE endpoint.

Inputs: page, pageSize.

hevy_list_routinesB

List routines. pageSize 1-10 (max enforced by server). Envelope: { page, page_count, routines }. No DELETE endpoint.

Inputs: page, pageSize.

hevy_list_workoutsA

List workouts newest-first, paginated. Use this to discover workout ids; fetch a single full record with hevy_get_workout, or just the count with hevy_get_workout_count. pageSize is 1-10 (Hevy returns 400 for >10). Response envelope: { page, page_count, workouts: [...] }. Empty account returns workouts: []. No DELETE endpoint exists on the Hevy API.

Inputs: page, pageSize.

hevy_search_exercise_templatesA

Find exercise templates by name. Paginates the full catalog (built-in + custom) and returns templates whose title contains the query, case-insensitive. Use this to resolve an exercise_template_id from a human name (e.g. "bench press") before composing a workout or routine. Response: { query, total_matches, exercise_templates: [...], truncated }. total_matches counts every match across the pages scanned; the scan stops after 30 pages of 100 — if the catalog is larger, truncated is true and total_matches is a lower bound. The catalog is cached for an hour.

Inputs: query (required), limit.

hevy_update_body_measurementA

Full replace of the body-measurements record for a date (PUT /v1/body_measurements/{date}). FULL REPLACE — any metric field NOT sent in body_measurement is overwritten to NULL on the server. To "update just one metric": call hevy_get_body_measurement for that date first, modify the metric you want, then send ALL fields back. Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: date (required), body_measurement (required).

hevy_update_routineA

Full replace of a routine (PUT /v1/routines/{id}). Omitted fields are dropped — to preserve a field, send it back unchanged. Each exercise needs an exercise_template_id (find via hevy_list_exercise_templates). Note: folder_id is NOT accepted on update; the Hevy API rejects it with 400. The routine's folder cannot be changed through this tool. Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process.

Inputs: routine (required), routineId (required).

hevy_update_workoutA

Full replace of a workout (PUT /v1/workouts/{id}). Any field not re-sent is dropped — to preserve a field, send it back unchanged. Each exercise needs an exercise_template_id (find via hevy_list_exercise_templates or hevy_get_exercise_template). Dry-run by default: returns { dry_run: true, executed: false, ... } unless HEVY_MCP_ALLOW_WRITES=1 is set on the server process. No DELETE endpoint exists on the Hevy API.

Inputs: workout (required), workoutId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool has a distinct purpose: user info, workouts, routines, folders, exercise templates, and body measurements are clearly separated. Even similar tools like list vs search templates are distinguishable by their descriptions.

    Naming Consistency5/5

    All tools use the 'hevy_verb_noun' pattern in snake_case, with verbs like get, list, create, update, search. The naming is uniform and predictable.

    Tool Count5/5

    23 tools cover the Hevy API's main domains (user, workouts, routines, exercise templates, body measurements) without being excessive. Each tool has a clear role.

    Completeness4/5

    Most CRUD operations are present, but deletions are missing (API limitation) and folder updates are not supported. These are minor gaps given the API constraints.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants to access and manage workout data, routines, exercise templates, and more through the Hevy API (requires PRO subscription).
      23
      545
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects AI clients to the Hevy workout tracking app, allowing users to manage routines and exercises. It enables reading workout history and logging new fitness sessions through simple natural language commands.
      -
    • A
      license
      B
      quality
      D
      maintenance
      A production-ready MCP server for the Hevy fitness API that exposes 27 tools for reading, writing, and analyzing workout data, enabling LLM-driven personal trainer workflows.
      27
      6 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that interfaces with the Hevy fitness tracking API, enabling AI assistants to manage workouts, routines, exercise templates, and more via natural language.
      26
      MIT