Hevy MCP Server

🚀 Hevy MCP Server

This is a server written in TypeScript and Node.js that connects your Hevy fitness data with language models through the Model Context Protocol (MCP). The server fetches data from the Hevy API and offers tools to access your workout history, progress, and personal bests.

🚀 Quick Start

What is MCP?

The Model Context Protocol (MCP) is a standard that enables large language models (LLMs) like Claude to integrate with external data sources and tools. This MCP server allows AI assistants to access and analyze your Hevy fitness data.

✨ Features

Available Tools

This MCP server provides the following tools:

• get-workouts: Retrieve workout records between specified start and end dates. Returns workouts sorted in descending order by date, with duration and total volume statistics. Displays up to 10 records.
• get-exercise-progress-by-ids: Track the progress of specific exercises over a period. Also includes the maximum record for each set.
• get-exercises: Obtain comprehensive workout data, sorted by usage frequency by default. Optional filters include name and date range. Also includes actual and estimated one-rep max (1RM).
• get-routines: Retrieve your saved training programs.

Intelligent Workout Tip Builder

This server includes an intelligent workout tip builder that:

• Analyzes your most frequently used exercises and their estimated one-rep max.
• Lists detailed exercise information and your saved training programs.
• Assists AI assistants in creating personalized workout suggestions based on your history.

📚 Documentation

Resource Documentation

The server provides detailed documentation for all available tools, accessible via a dedicated resource endpoint. This documentation includes:

• Detailed parameter descriptions.
• Valid ranges and default values for parameters.
• Example usage scenarios.

Obtain Your Hevy API Key

To obtain your Hevy API key, visit the Hevy API documentation and follow the authentication instructions. You need to register through the Hevy developer portal to gain API access.

Add to Cursor

To add this MCP server to Cursor, update your ~/.cursor/mcp.json file as follows:

"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 Details

For detailed technical information on installation, configuration, running the server, API endpoints, service methods, and project structure, refer to TECHNICAL.md.

📄 License

This project uses semantic-release for automated version control and package publishing. We follow the Conventional Commits specification for writing commit messages.