Hevy

You gain a practical MCP server that connects to the Hevy Fitness API to access and manage workouts, routines, exercise templates, folders, and webhook subscriptions through an interface that MCP-aware clients can use. It enables you to automate and script interactions with your Hevy data using the Model Context Protocol.

How to use

You interact with this server using an MCP-aware client. Start it with your API key and then perform actions such as fetching workouts, creating routines, browsing exercise templates, organizing routine folders, and managing webhook subscriptions for workout events.

How to install

Prerequisites you need before installing:

• Node.js 20+

Package manager: pnpm (via Corepack)

A Hevy API key with the appropriate access level

Install and run the server using the following concrete options.

Quick start commands

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

Manual installation steps

Clone the repository, install dependencies, and run locally.

git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

# Install dependencies via pnpm (require Corepack)
corepack use pnpm@10.22.0
pnpm install

# Create and populate environment file
cp .env.sample .env
# Edit .env and add HEVY_API_KEY

# Start the server with your API key
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

Configuration and usage notes

Configure how you connect by setting environment variables or passing command-line arguments. The API key is required to access Hevy data.

Integration with Cursor

To integrate with Cursor, add or merge an MCP server entry under the mcpServers configuration. The stdio-based approach shown here ensures the server runs locally and communicates via standard input/output.

{
  "mcpServers": {
    "hevy-mcp": {
      "command": "npx",
      "args": ["-y", "hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available tools

get-workouts

Fetch and format workout data from Hevy; supports listing workouts, with optional filters.

get-workout

Retrieve a single workout by its ID, returning detailed fields.

create-workout

Create a new workout with specified attributes and associate it with a routine or template as needed.

update-workout

Update properties of an existing workout, such as name, notes, or metadata.

get-workout-count

Return the total number of workouts stored for the connected Hevy account.

get-workout-events

Subscribe to or fetch events related to workouts, including updates and deletions.

get-routines

Fetch and format routine data to review or select existing routines.

create-routine

Create a new workout routine with its associated exercises and structure.

update-routine

Modify an existing routine’s details, such as exercises, order, or metadata.

get-routine-by-id

Retrieve a single routine by its unique ID from the Hevy API.

get-exercise-templates

Fetch available exercise templates for building workouts or routines.

get-exercise-template

Get details for a single exercise template by its ID.

get-routine-folders

Fetch folders used to organize routines for easier navigation.

create-routine-folder

Create a new folder to organize routines.

get-routine-folder

Retrieve a specific routine folder by its ID.

get-webhook-subscription

Fetch the current webhook subscription for workout events.

create-webhook-subscription

Create a new webhook subscription to receive workout event updates.

delete-webhook-subscription

Delete the existing webhook subscription for workout events.