Overview
What is Hevy MCP Server?
Hevy MCP Server is a TypeScript Node.js server that connects your Hevy workout data to language models via the Model Context Protocol (MCP). It fetches data from the Hevy API and provides tools for accessing workout history, exercise progress, and personal records, enabling AI assistants to analyze your workout data.
How to use Hevy MCP Server?
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.
Key features of Hevy MCP Server
- 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.
Use cases of Hevy MCP Server
- An AI assistant queries your recent workout history to suggest recovery adjustments.
- Automatically track progress on specific exercises over a chosen time period.
- Generate personalized workout plans based on your most-used exercises and saved routines.
- Retrieve and review your saved workout routines for planning or analysis.
FAQ from Hevy MCP Server
How do I obtain an API key for Hevy?
Visit the Hevy API Documentation and follow the authentication instructions. You need to sign up for API access through the Hevy developer portal.
What tools are available?
The server provides four tools: get-workouts, get-exercise-progress-by-ids, get-exercises, and get-routines.
Is there a limit on how many workouts I can fetch?
Yes, get-workouts returns a maximum of 10 workouts per call.
What environment variable is required?
The HEVY_API_KEY environment variable must be set to your Hevy API key.
How do I add this server to Cursor?
Update ~/.cursor/mcp.json with the command npx -y @vreippainen/hevy-mcp-server --stdio and the HEVY_API_KEY environment variable.
