hevy-mcp
Provides tools to access and manage workout data, routines, exercise templates, folders, body measurements, user info, and webhooks via the Hevy API (requires Hevy PRO subscription).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hevy-mcp show me my most recent workout"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hevy-mcp: Model Context Protocol Server for Hevy Fitness API
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 |
| Node.js ≥ 26, Hevy API key |
Local development |
|
|
🛠️ 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
Run via npx (Recommended)
You can launch the server directly without cloning:
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcpManual 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:
Environment Variable:
HEVY_API_KEY(in.envor system environment).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 |
|
Routines |
|
Templates |
|
Folders |
|
Body Measurements |
|
User |
|
Webhooks |
|
👨💻 Development & Contributing
Quick Commands
Build:
npm run buildLint/Format:
npm run check(uses oxlint/oxfmt)Unit Tests:
npx vitest run --exclude tests/integration/**Full Test Suite:
npm test(requiresHEVY_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
License: MIT
Credits: Model Context Protocol, Hevy Fitness.
Contributions are welcome! Please open an issue or PR for any major changes.
Available Tools
26 toolscreate-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-subscriptionADestructiveIdempotent
Delete the current webhook subscription for this account. This will stop all webhook notifications.
Inputs: no named parameters.
get-body-measurementARead-only
Get a single body measurement by date. Returns all measurement fields for the specified date.
Inputs: date (required).
get-body-measurementsARead-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-historyARead-only
Get past sets for a specific exercise template, optionally filtered by start and end dates.
Inputs: exerciseTemplateId (required), endDate, startDate.
get-exercise-templateARead-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-templatesARead-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-routineARead-only
Get a routine by its ID using the direct endpoint. Returns all details for the specified routine.
Inputs: routineId (required).
get-routine-folderARead-only
Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.
Inputs: folderId (required).
get-routine-foldersARead-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-routinesARead-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-infoARead-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-subscriptionARead-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-workoutARead-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-countARead-only
Get the total number of workouts on the account. Useful for pagination or statistics.
Inputs: no named parameters.
get-workout-eventsARead-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-workoutsARead-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-templatesARead-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-measurementADestructiveIdempotent
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-routineADestructiveIdempotent
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-workoutADestructiveIdempotent
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
Scored across 26 tools
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.
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.
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.
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
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
Create Hevy routines and analyze your training from chat. Unofficial; BYO Hevy PRO API key.
Fitness MCP for coaches and gyms: build workouts and read clients' training from live Superset data.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseAqualityAmaintenanceA 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).233,965 npm541MIT
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseNot gradedqualityNot gradedmaintenanceA 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 npmMIT
- AlicenseBqualityDmaintenanceMCP server for the Hevy workout tracker API that allows reading and writing workouts, routines, exercise templates, and body measurements.2211 npm1MIT