Hevy MCP is an integration that connects AI assistants to the Hevy fitness tracking platform, enabling programmatic management of workout data and training plans through the Hevy API. Key features include: - Workout management: retrieve training history and create or update workout sessions - Routine organization: access structured workout plans and organize them into folders - Exercise template library: browse Hevy's available exercises to build customized workouts - Webhook subscriptions: create and manage event notifications for workout changes - Real-time synchronization: keep training logs updated across the Hevy mobile app and other integrations Note: Requires a Hevy PRO subscription to access the Hevy API.

hevy-mcp: Model Context Protocol Server for Hevy Fitness API

[](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants to access and manage workout data, routines, exercise templates, and more through the Hevy API (requires PRO subscription).

Features

> Note: HTTP transport and Docker images are deprecated. The server runs via stdio transport (e.g., npx hevy-mcp). Legacy GHCR images remain available but are no longer maintained.

Quick start

Pick the workflow that fits your setup:

| Scenario | Command | Requirements | | --- | --- | --- | | One-off stdio run | HEVY_API_KEY=sk_live... npx -y hevy-mcp | Node.js ≥ 20, Hevy API key | | Local development | pnpm install && pnpm run dev | .env with HEVY_API_KEY, pnpm via Corepack |

Prerequisites

Installation

Run via npx (recommended)

You can launch the server directly without cloning:

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

Manual Installation

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp
Install dependencies
corepack use pnpm@10.22.0
pnpm install
Create .env and add your keys (never commit real keys)
cp .env.sample .env
Edit .env and add your HEVY_API_KEY.

Integration with Cursor

To use this MCP server with Cursor, add/merge this server entry under "mcpServers" in ~/.cursor/mcp.json:

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

Make sure to replace your-api-key-here with your actual Hevy API key.

If your mcp.json already contains other servers, do not replace the whole file—merge the "hevy-mcp" entry into your existing "mcpServers" object.

The "hevy-mcp" key name is arbitrary. If you already have an existing config using a different name (for example "hevy-mcp-server"), you can keep it.

If you already have an existing "mcpServers" object, merge the "hevy-mcp" entry into it without removing other servers.

Example full ~/.cursor/mcp.json

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

Configuration

You can supply your Hevy API key in two ways:

1. Environment variable (HEVY_API_KEY) 2. Command-line argument (--hevy-api-key=your_key or hevy-api-key=your_key after -- when using pnpm scripts)

Create a .env file in the project root (you can copy from .env.sample) with the following content if using the environment variable approach:

HEVY_API_KEY=your_hevy_api_key_here

Replace your_hevy_api_key_here with your actual Hevy API key. If you prefer the command argument approach you can skip setting the environment variable and start the server with for example:

pnpm start -- --hevy-api-key=your_hevy_api_key_here

Sentry monitoring

hevy-mcp ships with Sentry monitoring baked into the built MCP server so that usage and errors from published builds can be observed.

The server initializes @sentry/node with a fixed DSN, release name derived from the package version, and tracing settings directly in the code (see src/index.ts), and wraps the underlying McpServer with Sentry.wrapMcpServerWithSentry so requests and tool calls are captured by Sentry automatically. The configuration uses sendDefaultPii: false to keep Sentry's default PII collection disabled.

There is currently no built-in toggle to disable Sentry for the published package. If you need a build without Sentry telemetry, you can fork the repository and remove the Sentry initialization in src/index.ts.

Transport

Stdio Only (Current)

As of version 1.18.0, hevy-mcp only supports stdio transport. HTTP/SSE transport has been completely removed.

hevy-mcp runs exclusively over stdio, which works seamlessly with MCP-aware clients like Claude Desktop and Cursor. The server communicates via standard input/output streams using JSON-RPC messages.

Migration from HTTP/SSE Transport

**If you were using HTTP or SSE transport in an older version (< 1.18.0),