hevy

hevy-mcp is a Model Context Protocol server that integrates with the Hevy Fitness API. It exposes a set of MCP tools to manage workouts, routines, and exercise templates by leveraging the Hevy API (requires a PRO subscription). The server operates via stdio transport, meaning it communicates over standard input/output using JSON-RPC messages, which makes it suitable for MCP-aware clients like Claude Desktop and Cursor. You can start the server with npx hevy-mcp (or install locally and run via your preferred Node runtime) and provide your Hevy API key either through the HEVY_API_KEY environment variable or via command-line arguments. The server supports features such as fetching, creating, and updating workouts; managing routines and folders; browsing exercise templates; and handling webhook subscriptions for workout events.

Prerequisites:

• Node.js v20 or higher
• pnpm (via Corepack)
• A Hevy API key

Installation steps:

1. Quick start (run via npx, recommended):

HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

2. Manual installation (clone and install):

# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp

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

# Create environment config
cp .env.sample .env
# Edit .env and add your HEVY_API_KEY

3. Cursor integration (example for ~/.cursor/mcp.json):

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

4. If you need to migrate from HTTP/SSE transport, update client config to use stdio transport as shown above.

Notes and tips:

• Transport: As of v1.18.0, hevy-mcp uses stdio transport only. HTTP/SSE transport is deprecated and removed; ensure clients are configured for stdio.
• Sentry: The published MCP server includes Sentry monitoring. There is no built-in toggle to disable Sentry in the published package; to remove telemetry, fork and remove Sentry initialization in src/index.ts.
• Production vs development: Use pnpm run dev for development with hot reloading, or pnpm run build followed by pnpm start for production.
• Docker: Docker-based deployment is deprecated; running locally with npx hevy-mcp or your Node runtime is recommended.
• Environment variables: Provide HEVY_API_KEY securely via environment variables or via command-line arguments (e.g., --hevy-api-key=...).
• API scope: The server requires a PRO subscription to access Hevy API data such as workouts, routines, templates, and webhook events.