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 upstreamhevy-mcpnpm 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
- 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.envor 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:$PORTat/mcp - Health endpoint at
/healthz - Stateful sessions (
Mcp-Session-Idhonored) HEVY_API_KEYis 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(requiresHEVY_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.