Skip to main content
Glama
Sign In
Hevy MCP Pro

Hevy MCP Pro

by cbotworks
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@cdorneles/hevy-mcp-pro

A production-ready Model Context Protocol server for the Hevy fitness API. Exposes 27 tools for reading, writing, and analyzing your workout data — designed for "personal trainer via LLM" workflows in Claude Desktop, Claude Code, and Cursor.

CI npm version License: MIT

What sets this apart

Compared to the existing community Hevy MCP server, hevy-mcp-pro adds:

  • Local analytics: progression series, personal records (Epley 1RM), volume summaries, frequency stats, and stagnation detection — computed locally from your data, not via the Hevy API.

  • Smart fetching: single-exercise analytics use Hevy's /exercise_history endpoint (one call, full history) instead of paginating all workouts.

  • Robust HTTP client: token-bucket throttling, exponential backoff with jitter on 429/5xx, honors Retry-After, and never logs your API key.

  • Strict request validation: Zod schemas reject malformed payloads before they hit the Hevy API.

  • Convenience tools: duplicate_workout, routine_from_workout, compare_workouts.

Related MCP server: MCP-NG

Requirements

Quick start

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@cdorneles/hevy-mcp-pro"],
      "env": {
        "HEVY_API_KEY": "your-key-here"
      }
    }
  }
}

Restart Claude Desktop and you should see "hevy" in the MCP tool picker.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@cdorneles/hevy-mcp-pro"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

Claude Code

claude mcp add hevy npx -- -y @cdorneles/hevy-mcp-pro
# then set HEVY_API_KEY in the resulting config

Tools

Reading

Tool

Purpose

list_workouts

Paginate workouts (max pageSize 10 — Hevy API limit)

get_workout

Fetch a single workout with all sets

get_workout_count

Total workout count for the account

get_workout_events

Sync incremental updates/deletes since a timestamp

list_routines

Paginate routines

get_routine

Fetch a single routine

list_exercise_templates

Paginate exercise templates

get_exercise_template

Fetch one template

search_exercise_templates

Local fuzzy search across all templates (cached)

get_exercise_history

Flat history of every set for one exercise

list_routine_folders

Paginate folders

get_routine_folder

Fetch one folder

get_user_info

Authenticated user profile

Writing

Tool

Purpose

create_workout

Log a new workout

update_workout

Modify an existing workout

create_routine

Create a routine template

update_routine

Modify an existing routine

create_routine_folder

Create a new folder

create_exercise_template

Create a custom exercise

Analytics

Tool

Purpose

get_exercise_progression

Time series of best set per session for one exercise

get_personal_records

PRs (heaviest weight, best set, top estimated 1RM)

get_volume_summary

Volume grouped by exercise / muscle group / week

get_workout_frequency

Workouts/week, current streak, longest gap

detect_stagnation

Exercises whose 1RM has plateaued in the last N weeks

Convenience

Tool

Purpose

duplicate_workout

Re-log a past workout starting now (or at a given time)

routine_from_workout

Convert a logged workout into a reusable routine

compare_workouts

Side-by-side diff of two workouts

Configuration

All configuration is via environment variables.

Variable

Required

Default

Description

HEVY_API_KEY

yes

—

Your Hevy API key

LOG_LEVEL

no

info

error | warn | info | debug

HEVY_RATE_LIMIT_CAPACITY

no

10

Token bucket capacity (max burst)

HEVY_RATE_LIMIT_REFILL_PER_SEC

no

10

Token refill rate (requests/sec)

HEVY_ANALYTICS_MAX_PAGES

no

50

Soft cap for analytics pagination (50 pages = 500 workouts)

HEVY_CACHE_TTL_MS

no

3600000

Exercise template cache TTL (default 1h)

Example prompts

Once installed, you can ask your LLM things like:

"Show me my bench press progression over the last 3 months."

"What are my current personal records on squats, deadlifts, and bench?"

"Detect any exercises where I've stagnated in the last 8 weeks."

"Duplicate yesterday's workout and start it now."

"Compare my last two leg days."

"How many times did I train chest in March?"

Troubleshooting

Invalid API key or Hevy PRO subscription required

Confirm you have a Hevy PRO subscription and that the key from hevy.com/settings?p=developer is correctly set in HEVY_API_KEY. The key never appears in logs, so a typo is the most common cause.

Rate limited by Hevy API (retries exhausted)

The default client-side throttle is 10 req/s. If you're running heavy analytics queries against a long workout history, lower HEVY_RATE_LIMIT_REFILL_PER_SEC to e.g. 5 to slow down further.

Analysis limited to first 500 workouts

Analytics tools paginate workouts with a soft cap. Raise HEVY_ANALYTICS_MAX_PAGES if you need to analyze deeper history. Each page is up to 10 workouts.

Logs

This server writes structured JSON logs to stderr (stdout is reserved for the MCP protocol). To debug, set LOG_LEVEL=debug and check your MCP client's server log view.

Development

git clone https://github.com/cbotworks/mcp-hevy-pro.git
cd hevy-mcp-pro
pnpm install
pnpm test       # 41+ unit tests, no network
pnpm typecheck
pnpm lint
pnpm build      # produces dist/ (ESM + CJS + .d.ts)

To regenerate the vendored OpenAPI snapshot:

pnpm fetch-openapi

Architecture

src/
├── client/         HTTP layer (rate limiter, retry, error mapping, paginator)
├── schemas/        Zod schemas for API requests + responses
├── tools/          Tool implementations grouped by domain
│   └── analytics/  Pure analyzers (progression, PRs, volume, frequency, stagnation)
├── utils/          Logger, errors, TTL cache
├── server.ts       MCP server: registers tools, wires stdio transport
└── index.ts        CLI entry: parses env, fails fast on missing API key

The HTTP client owns all network I/O. Tools never call fetch directly. Analytics tools are pure functions over data fetched via the client, which makes them trivially fixture-testable.

Contributing

Issues and PRs welcome. Please run pnpm typecheck && pnpm lint && pnpm test before submitting.

License

MIT — see LICENSE.

Acknowledgements

The Hevy team for the public API. The community chrisdoc/hevy-mcp server informed early API exploration but no code was reused.

Available Tools

27 tools
compare_workoutsA

Compare two workouts side-by-side. Returns per-workout summaries, top-level deltas (volume, sets, exercise count), and a per-exercise diff sorted alphabetically by exercise title.

Inputs: workoutIdA (required), workoutIdB (required).

create_exercise_templateB

Create a custom exercise template. Requires title, exercise_type, equipment_category, and muscle_group; other_muscles is optional.

Inputs: exercise (required).

create_routineA

Create a new routine. Routines may optionally live inside a folder via folder_id. Note: the Hevy mobile app does not render rep_range (it uses an undocumented input_modifier field).

Inputs: routine (required).

create_routine_folderA

Create a new routine folder with the given title. All other fields (id, index, timestamps) are assigned by the server.

Inputs: title (required).

create_workoutA

Create a new workout. The workout body is strictly validated: title, start_time/end_time (ISO 8601), and at least one exercise with at least one set are required.

Inputs: workout (required).

detect_stagnationA

Flag exercises whose peak estimated 1RM occurred earlier in the window (i.e. recent sessions are below peak). Defaults: weeksBack=8, minSessions=3. Returns a list sorted by percent below peak, descending. May include a warning field if truncated.

Inputs: weeksBack, minSessions.

duplicate_workoutA

Duplicate an existing workout. The new workout starts at startTime (defaults to now) and preserves the original's duration, title, exercises, and sets.

Inputs: workoutId (required), startTime.

get_exercise_historyA

Fetch per-set history for a single exercise template across all workouts. Optionally bounded by startDate/endDate (ISO 8601). Much cheaper than paginating /v1/workouts when you only care about one exercise.

Inputs: templateId (required), endDate, startDate.

get_exercise_progressionA

Return a chronological time series of the best set per session for one exercise template. Uses /v1/exercise_history (single API call). Each point includes weight, reps, volume, and Epley-estimated 1RM. Optional since (ISO 8601) defaults to 90 days ago.

Inputs: exerciseTemplateId (required), since.

get_exercise_templateA

Fetch a single exercise template by its ID.

Inputs: templateId (required).

get_personal_recordsA

Return heaviest-weight, best-set (weight * reps), and top estimated 1RM PRs. If exerciseTemplateId is provided, uses /v1/exercise_history (single call). Otherwise paginates recent workouts and returns a per-exercise map. May include a warning field if paginated results were truncated.

Inputs: since, exerciseTemplateId.

get_routineA

Fetch a single routine by its ID, including all planned exercises and sets.

Inputs: routineId (required).

get_routine_folderA

Fetch a single routine folder by its numeric ID.

Inputs: folderId (required).

get_user_infoA

Fetch the authenticated user's profile (id, name, public profile URL).

Inputs: no named parameters.

get_volume_summaryA

Total training volume (weight_kg * reps, nulls => 0) grouped by exercise, muscle_group, or week. Paginates recent workouts since since (ISO 8601, default 90 days ago). May include a warning field if results were truncated.

Inputs: since, groupBy.

get_workoutA

Fetch a single workout by its ID, including all exercises and logged sets.

Inputs: workoutId (required).

get_workout_countA

Get the total number of workouts logged for the authenticated account.

Inputs: no named parameters.

get_workout_eventsA

List workout sync events (created/updated/deleted) since a given ISO 8601 timestamp. Useful for incremental sync. Hevy enforces a max pageSize of 10.

Inputs: since (required), page, pageSize.

get_workout_frequencyA

Per-week workout counts with streak and longest-gap statistics over since (ISO 8601, default 90 days ago). May include a warning field if results were truncated.

Inputs: since.

list_exercise_templatesA

List exercise templates (built-in and custom). Hevy enforces a max pageSize of 10. For fuzzy name search prefer search_exercise_templates.

Inputs: page, pageSize.

list_routine_foldersC

List routine folders. Hevy enforces a max pageSize of 10.

Inputs: page, pageSize.

list_routinesB

List saved routines (workout templates). Hevy enforces a max pageSize of 10.

Inputs: page, pageSize.

list_workoutsB

List workouts in reverse-chronological order. Hevy enforces a max pageSize of 10.

Inputs: page, pageSize.

routine_from_workoutA

Create a new routine from an existing workout. Copies exercises and sets (dropping RPE, which routines do not support) and places the routine in the given folder, if any.

Inputs: title (required), workoutId (required), folderId.

search_exercise_templatesA

Fuzzy-search exercise templates by name with an optional muscle-group filter. Runs locally against a cached copy of all templates — much faster and cheaper than paginating /v1/exercise_templates. Returns top matches sorted by score.

Inputs: query (required), limit, muscleGroup.

update_routineA

Replace an existing routine by ID. Note: the API does NOT accept folder_id on update — folder moves happen via the mobile app only.

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

update_workoutA

Replace an existing workout by ID. The full workout body must be supplied — this is a full replacement, not a patch.

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

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 27 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action, with clear separation between list/get/create/update and analytical operations. Even similar tools like search_exercise_templates and list_exercise_templates have clearly differentiated purposes described in their summaries.

    Naming Consistency4/5

    The vast majority of tools follow a consistent verb_noun snake_case pattern (e.g., list_workouts, create_workout, get_exercise_history). The single exception is 'routine_from_workout', which deviates from the pattern but remains readable and clear.

    Tool Count3/5

    With 27 tools, the server is heavier than the ideal 3-15 range, but the breadth covers multiple entities (workouts, routines, templates, folders) plus analytics. The count feels justified for a feature-rich API, though it is borderline excessive.

    Completeness2/5

    The server lacks delete operations for all entities (workouts, routines, exercise templates, routine folders), preventing full lifecycle management. While CRUD for create/get/update exists, the inability to delete creates dead ends and forces workarounds.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP-NG

      Lotargo
      A
      license
      Not graded
      quality
      Not graded
      maintenance
      A high-performance Go-based MCP server that provides a microservice architecture for orchestrating diverse tools through gRPC and HTTP/REST APIs. Enables seamless integration of language-agnostic tools including ML capabilities, web search, calculations, and human interaction for intelligent agent workflows.
      2
      -

    • awesome-mineflayer-mcp

      G0Osey99
      A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that gives an LLM agent standalone-equivalent control over a Mineflayer Minecraft bot — movement, mining, crafting, inventory, combat, containers, chat, and much more — exposed as 110 strongly-typed tools across 23 groups, with full bot lifecycle management and dual (poll + push) event streaming.
      142 npm
      8
      MIT