Hevy MCP Server

@VReippainen

About Hevy MCP Server

No overview available yet

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "hevy-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@vreippainen/hevy-mcp-server",
        "--stdio"
      ],
      "env": {
        "HEVY_API_KEY": ""
      }
    }
  }
}

Tools

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

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.

Frequently asked questions

How do I obtain an API key for Hevy?

Visit the [Hevy API Documentation](https://api.hevyapp.com/docs/#/) 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.

Comments

Basic information

More Other MCP servers

MCP Registry

modelcontextprotocol

A community driven registry service for Model Context Protocol (MCP) servers.

7.0K

MaxKB

1Panel-dev

🔥 MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。

22.0K

DeepMark

DeepMark helps teachers deliver rapid, consistent marking with meaningful feedback for every student — in a fraction of the time. What once took a week, now takes one free period.

Codelf

unbug

A search tool helps dev to solve the naming things problem.

14.2K

Blender

ahujasid

Open-source MCP to use Blender with any LLM

23.6K