Hevy MCP (Remote)

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

[License: MIT] [Build Docker image] [ghcr.io]

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:

🛠️ 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 repositorygit clone https://github.com/chrisdoc/hevy-mcp.gitcd hevy-mcp
# Install dependenciesnpm install
# Create .env and add your keyscp .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:

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

# Example .envHEVY_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:localcurl 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

👨‍💻 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.