Skip to main content
Glama

hevy-mcp: Model Context Protocol Server for Hevy Fitness API

License: MIT Build and Test Codecov npm version

A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants like Claude Desktop and Cursor to access and manage workout data, routines, and exercise templates through the Hevy API (requires PRO subscription).


📋 Table of Contents


Related MCP server: Hevy MCP

🚀 Features

  • Workout Management: Fetch, create, and update workouts.

  • Routine Management: Access and manage workout routines.

  • Exercise Templates: Browse available exercise templates with in-memory caching.

  • Folder Organization: Manage routine folders.

  • Webhook Subscriptions: Create, view, and delete webhook subscriptions for workout events.


🏁 Quick Start

Pick the workflow that fits your setup:

Scenario

Command

Requirements

One-off stdio run

HEVY_API_KEY=sk_live... npx -y hevy-mcp

Node.js ≥ 26, Hevy API key

Local development

npm install && npm run build && npm start

.env with HEVY_API_KEY


🛠️ Prerequisites

  • Node.js: v26 or higher (strongly recommended to use the exact version pinned in .nvmrc).

  • npm: v10 or higher.

  • Hevy API key: Required for all operations (available with Hevy PRO).


📦 Installation

You can launch the server directly without cloning:

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

Manual Installation

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies
npm install

# Create .env and add your keys
cp .env.sample .env
# Edit .env and add your HEVY_API_KEY

🔗 Integration

Claude Desktop Configuration

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"hevy-mcp": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "sk_live_your_key_here"
			}
		}
	}
}

Cursor Configuration

Add this server under "mcpServers" in ~/.cursor/mcp.json:

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

Other MCP Clients (via add-mcp)

For a generic setup flow across MCP clients, use add-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=secret"

This bootstraps the hevy-mcp entry in your client config without manual JSON edits.


✨ Why hevy-mcp?

  • 🚀 High Performance: Built with the Oxc toolchain (oxlint/oxfmt) for near-instant linting and formatting.

  • 🛡️ Type Safety: Fully type-safe implementation using Zod and Kubb-generated API clients.

  • 📉 Observability: Built-in Sentry monitoring for error tracking, lifecycle and tool tracing, and stdio parse diagnostics.

  • ⚡ Optimized: Includes in-memory caching for exercise templates to reduce API latency.


⚙️ Configuration

Supply your Hevy API key via:

  1. Environment Variable: HEVY_API_KEY (in .env or system environment).

  2. CLI Argument: --hevy-api-key=your_key (after -- in npm scripts).

# Example .env
HEVY_API_KEY=your_hevy_api_key_here

📡 Sentry Monitoring

hevy-mcp includes Sentry monitoring to observe errors and usage in production. It initializes @sentry/node with tracing enabled and PII collection disabled by default. Recent observability changes also add:

  • lifecycle spans around server build, run, and stdio connect

  • per-tool execution spans plus captured handler exceptions

  • stdio parse diagnostics, including leading UTF-8 BOM stripping and invalid JSON context

  • a deterministic pseudonymous Sentry user ID derived from HEVY_API_KEY, so the raw key is never sent to Sentry


Stdio Only

As of version 1.18.0, hevy-mcp only supports stdio transport. HTTP/SSE transport has been completely removed to simplify the codebase and focus on the native MCP experience.

Docker

Docker-based workflows are retired. The provided Dockerfile now exits with a message pointing to the stdio-native experience. Legacy GHCR images are no longer updated.


🛠️ Available MCP Tools

Category

Tools

Workouts

get-workouts, get-workout, create-workout, update-workout, get-workout-count, get-workout-events

Routines

get-routines, get-routine, create-routine, update-routine

Templates

get-exercise-templates, get-exercise-template, search-exercise-templates, create-exercise-template, get-exercise-history

Folders

get-routine-folders, get-routine-folder, create-routine-folder

Body Measurements

get-body-measurements, get-body-measurement, create-body-measurement, update-body-measurement

User

get-user-info

Webhooks

get-webhook-subscription, create-webhook-subscription, delete-webhook-subscription


👨‍💻 Development & Contributing

Quick Commands

  • Build: npm run build

  • Lint/Format: npm run check (uses oxlint/oxfmt)

  • Unit Tests: npx vitest run --exclude tests/integration/**

  • Full Test Suite: npm test (requires HEVY_API_KEY)

For a detailed senior engineer guide, please refer to AGENTS.md.

API Client Generation

The API client is automatically generated from the OpenAPI spec using Kubb:

npm run build:client

📄 License & Acknowledgements


Contributions are welcome! Please open an issue or PR for any major changes.

Available Tools

26 tools
create-body-measurementA

Create a body measurement entry for a given date. All measurement fields are optional; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Returns 409 if an entry already exists for that date — use update-body-measurement instead.

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

create-exercise-templateB

Create a custom exercise template with title, type, equipment, and muscle groups.

Inputs: title (required), muscleGroup (required), exerciseType (required), equipmentCategory (required), +1 more.

create-routineA

Create a new workout routine in your Hevy account. Requires a title and at least one exercise with sets. Optionally assign to a folder. Returns the full routine details including the new routine ID.

Inputs: title (required), notes, folderId, exercises.

create-routine-folderA

Create a new routine folder in your Hevy account. Requires a name for the folder. Returns the full folder details including the new folder ID.

Inputs: name (required).

create-webhook-subscriptionA

Create a new webhook subscription for this account. The webhook will receive POST requests when workouts are created. Your endpoint must respond with 200 OK within 5 seconds.

Inputs: url (required), authToken.

create-workoutA

Create a new workout in your Hevy account. Requires title, start/end times, and at least one exercise with sets. Returns the complete workout details upon successful creation including the newly assigned workout ID.

Inputs: title (required), endTime (required), startTime (required), exercises, +2 more.

delete-webhook-subscriptionA
DestructiveIdempotent

Delete the current webhook subscription for this account. This will stop all webhook notifications.

Inputs: no named parameters.

get-body-measurementA
Read-only

Get a single body measurement by date. Returns all measurement fields for the specified date.

Inputs: date (required).

get-body-measurementsA
Read-only

Get a paginated list of body measurements for the authenticated user. Returns measurements including weight, body fat, and various circumference measurements.

Inputs: page, pageSize.

get-exercise-historyA
Read-only

Get past sets for a specific exercise template, optionally filtered by start and end dates.

Inputs: exerciseTemplateId (required), endDate, startDate.

get-exercise-templateA
Read-only

Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.

Inputs: exerciseTemplateId (required).

get-exercise-templatesA
Read-only

Get a paginated list of exercise templates (default and custom) with details like name, category, equipment, and muscle groups. Useful for browsing or searching available exercises.

Inputs: page, pageSize.

get-routineA
Read-only

Get a routine by its ID using the direct endpoint. Returns all details for the specified routine.

Inputs: routineId (required).

get-routine-folderA
Read-only

Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.

Inputs: folderId (required).

get-routine-foldersA
Read-only

Get a paginated list of your routine folders, including both default and custom folders. Useful for organizing and browsing your workout routines.

Inputs: page, pageSize.

get-routinesA
Read-only

Get a paginated list of your workout routines, including custom and default routines. Useful for browsing or searching your available routines.

Inputs: page, pageSize.

get-user-infoA
Read-only

Get the authenticated user's account info, including user ID, display name, and public profile URL. Useful for verifying which account the API key belongs to.

Inputs: no named parameters.

get-webhook-subscriptionA
Read-only

Get the current webhook subscription for this account. Returns the webhook URL and auth token if a subscription exists.

Inputs: no named parameters.

get-workoutA
Read-only

Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.

Inputs: workoutId (required).

get-workout-countA
Read-only

Get the total number of workouts on the account. Useful for pagination or statistics.

Inputs: no named parameters.

get-workout-eventsA
Read-only

Retrieve a paged list of workout events (updates or deletes) since a given date. Events are ordered from newest to oldest. The intention is to allow clients to keep their local cache of workouts up to date without having to fetch the entire list of workouts.

Inputs: page, since, pageSize.

get-workoutsA
Read-only

Get a paginated list of workouts. Returns workout details including title, description, start/end times, and exercises performed. Results are ordered from newest to oldest.

Inputs: page, pageSize.

search-exercise-templatesA
Read-only

Search exercise templates by name with optional muscle group filter. Fetches all templates from the Hevy API on first call and caches them in memory for subsequent searches. Use refresh:true to force a re-fetch.

Inputs: query (required), refresh, primaryMuscleGroup.

update-body-measurementA
DestructiveIdempotent

Update an existing body measurement entry for a given date. Only the fields you provide are sent and updated; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Requires at least one measurement field. Returns 404 if no entry exists for the date.

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

update-routineA
DestructiveIdempotent

Update an existing routine by ID. You can modify the title, notes, and exercise configurations. Returns the updated routine with all changes applied.

Inputs: title (required), routineId (required), notes, exercises.

update-workoutA
DestructiveIdempotent

Update an existing workout by ID. You can modify the title, description, start/end times, privacy setting, and exercise data. Returns the updated workout with all changes applied.

Inputs: title (required), endTime (required), startTime (required), workoutId (required), +3 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 26 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear names that prevent confusion. For example, get-exercise-template vs get-exercise-templates vs search-exercise-templates are unambiguous.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern using snake_case, such as create-body-measurement, get-workouts, delete-webhook-subscription. No mixing of styles.

    Tool Count4/5

    With 26 tools covering multiple resources (body measurements, exercises, routines, folders, webhooks, workouts, user info), the count is slightly high but still well-scoped for a fitness tracking server.

    Completeness3/5

    Several resources lack delete operations (e.g., body measurements, routines, workouts) and some lack updates (exercise templates, routine folders). While the core workflows are covered, these gaps are notable and could cause agent inconvenience.

    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
      3,965 npm
      541
      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
      Not graded
      quality
      Not graded
      maintenance
      A Model Context Protocol (MCP) server that provides AI assistants with access to the Hevy fitness tracking API. This allows you to log workouts, manage routines, browse exercises, and track your fitness progress directly through AI chat interfaces.
      13 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server for the Hevy workout tracker API that allows reading and writing workouts, routines, exercise templates, and body measurements.
      22
      11 npm
      1
      MIT