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:

🛠️ 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-ins

... View full README on GitHub