About Hevy MCP Server
Hevy MCP Server is a TypeScript Node.js service that makes Hevy workout data available to language models. It is for users reviewing workout history and progress, and can build workout prompts from frequently used exercises, estimated 1RMs, and saved routines.
Key features
- 01Retrieve workouts by date range
- 02Track exercise progress and rep records
- 03Filter exercises and view actual and estimated 1RMs
- 04Retrieve saved workout routines
- 05Build prompts from workout history
Use cases
- 01Review workout volume and duration over a period
- 02Track long-term progress for selected exercises
- 03Generate personalized recommendations from workout history
MCP support
The MCP server fetches data from the Hevy API and exposes tools for workout history, exercise progress, exercise data, and routines. It also provides a resource documenting tool parameters and a workout prompt builder.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
4Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Number of workouts to retrieve |
| startDate | string | No | Optional: ISO date string to filter workouts after this date |
| endDate | string | No | Optional: ISO date string to filter workouts before this date |
Details
From the project READMEHevy MCP Server
A TypeScript Node.js server that connects your Hevy workout data to Language Models via Model Context Protocol (MCP). The server fetches data from the Hevy API and provides tools for accessing your workout history, exercise progress, and personal records.
What is MCP?
Model Context Protocol (MCP) is a standard that allows LLMs like Claude to integrate with external data sources and tools. This MCP server enables AI assistants to access and analyze your Hevy workout data.
Available Tools
This MCP server provides the following tools:
- get-workouts: Get workouts between start and end dates. Returns workouts in descending order of date with duration and volume stats. Max 10 workouts.
- get-exercise-progress-by-ids: Track progress for specific exercises over time, filtered by date range. Returns also records per reps.
- get-exercises: Get comprehensive exercise data sorted by frequency of use, with optional filtering by name and date range. Returns also actual and estimated 1RM.
- get-routines: Retrieve your saved workout routines
Workout Prompt Builder
The server includes a smart workout prompt builder that:
- Analyzes your most frequently used exercises and their estimated 1RMs
- Lists your saved workout routines with detailed exercise information
- Helps AI assistants create personalized workout recommendations based on your history
Resource Documentation
The server provides comprehensive documentation of all available tools and their parameters through a dedicated resource endpoint. This documentation includes:
- Detailed parameter descriptions
- Valid parameter ranges and defaults
- Example usage scenarios
Obtaining Your Hevy API Key
To get your Hevy API key, visit the Hevy API Documentation and follow the authentication instructions. You'll need to sign up for API access through the Hevy developer portal.
Adding to Cursor
To add this MCP server to Cursor, update your ~/.cursor/mcp.json file with the following configuration:
"hevy-mcp-server": {
"command": "npx",
"args": ["-y", "@vreippainen/hevy-mcp-server", "--stdio"],
"env": {
"HEVY_API_KEY": "your-api-key-here"
}
}
Replace your-api-key-here with your actual Hevy API key.
Technical Documentation
For detailed technical information about installation, configuration, running the server, API endpoints, service methods, and project structure, see TECHNICAL.md.
Release Process
This project uses semantic-release for automated versioning and package publishing. We follow the Conventional Commits specification for commit messages.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.