Hevy MCP Server
Description
# Hevy 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. ##…
About
# Hevy 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)…
Details
- Author
- VReippainen
- GitHub stars
- 3
- Downloads
- 189
- Categories
- Other
Jump to
- get-workouts: Retrieve up to 10 workouts within a date range with duration and volume stats.
- get-exercise-progress-by-ids: Track progress for specific exercises over time, filtered by date range.
- get-exercises: Get comprehensive exercise data sorted by frequency, with optional name and date filtering.
- get-routines: Retrieve your saved workout routines.
- Workout prompt builder: Analyzes frequent exercises and routines to help AI create personalized recommendations.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Hevy MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install and invoke by adding a configuration to your ~/.cursor/mcp.json file using npx and setting the HEVY_API_KEY environment variable. Then use the provided tools (e.g., get-workouts, get-exercises) through an MCP‑compatible client.
get-workouts
Get workouts between start and end dates. Returns all workouts if no dates are provided. Returns workouts in descending order of date and limits the number of workouts returned. Max 10 workouts. Example: { "limit": 5, // Optional: Number of workouts (1-10, default: 10) "startDate": "2024-01-01T00:00:00Z", // Optional: Filter workouts after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Filter workouts before this date }
get-exercise-progress-by-ids
Get progress history for specific exercises between start and end dates. Returns exercise data including weights, reps, and sets for each workout. Results are ordered by date descending. Useful for tracking progress over time for particular exercises. Example: { "exerciseIds": ["bench-press-123", "squat-456"], // Required: Array of exercise IDs "limit": 5, // Optional: Number of workouts (0-10, default: 10) "startDate": "2024-01-01T00:00:00Z", // Optional: Filter after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Filter before this date }
get-exercises
Get comprehensive exercise data including frequency of use, categorization, and metadata. Results are sorted by usage frequency. Supports filtering by name search and date range. Example: { "searchTerm": "bench press", // Optional: Filter exercises by name "excludeUnused": true, // Optional: Skip never-performed exercises (default: true) "startDate": "2024-01-01T00:00:00Z", // Optional: Consider usage after this date "endDate": "2024-03-20T23:59:59Z" // Optional: Consider usage before this date }
get-routines
Get user's saved workout routines. Returns all custom and preset routines with their full exercise details, including sets, reps, and rest periods. Example: {} // No parameters required
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"hevy mcp server": {
"hevy-mcp-server": {
"command": "npx",
"args": [
"-y",
"@vreippainen/hevy-mcp-server",
"--stdio"
],
"env": {
"HEVY_API_KEY": ""
}
}
}
}
}McpServers
{
"hevy-mcp-server": {
"command": "npx",
"args": [
"-y",
"@vreippainen/hevy-mcp-server",
"--stdio"
],
"env": {
"HEVY_API_KEY": ""
}
}
}Hevy 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.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
