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.