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 to provide access to workout history, exercise progress, and personal records.

Use cases

Use cases include tracking workout history, monitoring exercise progress over time, retrieving specific exercise data for analysis, and managing personalized workout routines.

How to use

To use Hevy MCP Server, obtain your Hevy API key from the Hevy API Documentation. Then, configure your Cursor by updating the ‘~/.cursor/mcp.json’ file with the server command and your API key. Finally, run the server to start accessing your workout data.

Key features

Key features include tools to get workouts by date, track exercise progress, retrieve comprehensive exercise data, and access saved workout routines. The server supports a maximum of 10 workouts returned in descending order by date.

Where to use

Hevy MCP Server is useful in fitness and health applications, particularly for developers creating AI assistants that analyze workout data and provide insights based on user performance.

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:

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.