hevy-mcp-remote: Hosted / gateway-ready MCP for Hevy Fitness

Fork notice. This is an independently-maintained fork of chrisdoc/hevy-mcp, repackaged for multi-tenant MCP gateways. It ships the same Hevy tools wrapped in supergateway as an OCI image that speaks MCP streamable-HTTP over HTTP, instead of stdio. Use the upstream hevy-mcp npm package for local/stdio use in Claude Desktop, Cursor, etc.

A Model Context Protocol (MCP) server for the Hevy fitness tracking app, packaged as a supergateway-wrapped OCI image for hosting behind an MCP gateway. Exposes MCP streamable-HTTP on /mcp and health on /healthz; reads HEVY_API_KEY from the container environment.

📋 Table of Contents

Features
Quick Start
Prerequisites
Installation
- Claude Desktop Configuration
- Cursor Configuration
Why hevy-mcp?
Configuration
Available MCP Tools
Development & Contributing

🚀 Features

Workout Management: Fetch, create, and update workouts.
Routine Management: Access and manage workout routines.
Exercise Templates: Browse available exercise templates with in-memory caching.
Folder Organization: Manage routine folders.
Webhook Subscriptions: Create, view, and delete webhook subscriptions for workout events.

🏁 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 ≥ 24, Hevy API key
Local development	`npm install && npm run build && npm start`	`.env` with `HEVY_API_KEY`

🛠️ Prerequisites

Node.js: v24 or higher (strongly recommended to use the exact version pinned in .nvmrc).
npm: v10 or higher.
Hevy API key: Required for all operations (available with Hevy PRO).

📦 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
npm install

# Create .env and add your keys
cp .env.sample .env
# Edit .env and add your HEVY_API_KEY

🔗 Integration

Claude Desktop Configuration

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"hevy-mcp": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "sk_live_your_key_here"
			}
		}
	}
}

Cursor Configuration

Add this server under "mcpServers" in ~/.cursor/mcp.json:

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

✨ Why hevy-mcp?

🚀 High Performance: Built with the Oxc toolchain (oxlint/oxfmt) for near-instant linting and formatting.
🛡️ Type Safety: Fully type-safe implementation using Zod and Kubb-generated API clients.
📉 Observability: Built-in Sentry monitoring for error tracking and performance profiling.
⚡ Optimized: Includes in-memory caching for exercise templates to reduce API latency.

⚙️ Configuration

Supply your Hevy API key via:

Environment Variable: HEVY_API_KEY (in .env or system environment).
CLI Argument: --hevy-api-key=your_key (after -- in npm scripts).

# Example .env
HEVY_API_KEY=your_hevy_api_key_here

📡 Sentry Monitoring

hevy-mcp includes Sentry monitoring to observe errors and usage in production. It initializes @sentry/node with tracing enabled and PII collection disabled by default.

🐳 Running behind an MCP gateway (supergateway contract)

The MCP server itself speaks stdio only. For multi-tenant gateway deployments (e.g. mcp-gateway-poc), this repo ships a Dockerfile that wraps the stdio binary with supergateway so a single container exposes MCP streamable-HTTP.

The image follows the same contract every gateway-hosted MCP uses:

MCP streamable-HTTP on 0.0.0.0:$PORT at /mcp
Health endpoint at /healthz
Stateful sessions (Mcp-Session-Id honored)
HEVY_API_KEY is read from the container environment and passed to the spawned stdio child

Images are published to ghcr.io/rwestergren/hevy-mcp from main and from any manually cut GitHub release. Build locally with:

docker build -t hevy-mcp:local .
docker run --rm -e HEVY_API_KEY=sk_live_... -p 8080:8080 hevy-mcp:local
curl http://localhost:8080/healthz

End users running hevy-mcp directly should use the stdio/npx flow above; the Docker image is aimed at gateway operators, not individual clients.

🛠️ Available MCP Tools

Category	Tools
Workouts	`get-workouts`, `get-workout`, `create-workout`, `update-workout`, `get-workout-count`, `get-workout-events`
Routines	`get-routines`, `get-routine-by-id`, `create-routine`, `update-routine`
Templates	`get-exercise-templates`, `get-exercise-template`, `search-exercise-templates`
Folders	`get-routine-folders`, `get-routine-folder`, `create-routine-folder`
Webhooks	`get-webhook-subscription`, `create-webhook-subscription`, `delete-webhook-subscription`

👨‍💻 Development & Contributing

Quick Commands

Build: npm run build
Lint/Format: npm run check (uses oxlint/oxfmt)
Unit Tests: npx vitest run --exclude tests/integration/**
Full Test Suite: npm test (requires HEVY_API_KEY)

For a detailed senior engineer guide, please refer to AGENTS.md.

API Client Generation

The API client is automatically generated from the OpenAPI spec using Kubb:

npm run build:client

📄 License & Acknowledgements

License: MIT
Credits: Model Context Protocol, Hevy Fitness.

Contributions are welcome! Please open an issue or PR for any major changes.

Hevy MCP (Remote)