hevy-mcp: Model Context Protocol Server for Hevy Fitness API

A Model Context Protocol (MCP) server implementation that interfaces with the Hevy fitness tracking app and its API. This server enables AI assistants like Claude Desktop and Cursor to access and manage workout data, routines, and exercise templates through the Hevy API (requires PRO subscription).

📋 Table of Contents

• Features
• Quick Start
• Prerequisites
• Installation
  • Run with Docker
  • Claude Desktop Configuration
  • Cursor Configuration
  • Other MCP Clients (via add-mcp)
• Why hevy-mcp?
• Configuration
• Available MCP Tools
• Available MCP Resources
• 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.

🏁 Quick Start

Pick the workflow that fits your setup:

🛠️ Prerequisites

• Node.js: v20 or higher (strongly recommended to use the exact version pinned in .nvmrc).
• npm: v10 or higher.
• Bun (optional): If you want to launch with bunx.
• Docker (optional): If you want an isolated container-based stdio setup.
• Hevy API key: Required for all operations (available with Hevy PRO).

📦 Installation

Run via npx or bunx

You can launch the server directly without cloning. Both launchers are covered by nightly smoke tests:

# npm launcher
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp

# bun launcher
HEVY_API_KEY=your_hevy_api_key_here bunx hevy-mcp@latest

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

Run with Docker

Official multi-platform images are published to GitHub Container Registry for linux/amd64 and linux/arm64:

export HEVY_API_KEY=your_hevy_api_key_here
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

The server uses stdio, so -i keeps standard input open for the MCP client. --rm removes the stopped container automatically. The -e HEVY_API_KEY form forwards the variable from the host environment without putting the key in the command arguments.

Use latest to follow the newest stable release. For reproducible deployments, pin the exact version shown on the release, using a tag such as ghcr.io/chrisdoc/hevy-mcp:X.Y.Z. Major (:X) and major.minor (:X.Y) tags are also published for controlled automatic updates.

🔗 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"
			}
		}
	}
}

If you prefer Bun, swap the launcher fields:

{
	"command": "bunx",
	"args": ["hevy-mcp@latest"]
}

To run Claude Desktop through Docker instead, first create an environment file outside the repository containing your real key:

HEVY_API_KEY=replace_with_your_real_key

Restrict access to that file where supported (for example, chmod 600 /absolute/path/to/hevy-mcp.env), then use its absolute path in the Claude Desktop configuration:

{
	"mcpServers": {
		"hevy-mcp": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"--env-file",
				"/absolute/path/to/hevy-mcp.env",
				"ghcr.io/chrisdoc/hevy-mcp:latest"
			]
		}
	}
}

This configuration runs the same stdio server inside the container; it does not expose an HTTP port or start a detached service. Docker reads the key from the environment file, so the Claude configuration does not replace an inherited key with a placeholder. Replace latest with an exact version tag if you want Claude Desktop to stay on a pinned release.

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"
			}
		}
	}
}

If you prefer Bun, swap the launcher fields:

{
	"command": "bunx",
	"args": ["hevy-mcp@latest"]
}

Other MCP Clients (via add-mcp)

For a generic setup flow across MCP clients, use add-mcp:

npx add-mcp hevy-mcp --env "HEVY_API_KEY=secret"

This bootstraps the hevy-mcp entry in your client config without manual JSON edits.

✨ 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, lifecycle and tool tracing, and stdio parse diagnostics.
• ⚡ Optimized: Includes in-memory caching for exercise templates to reduce API latency.

⚙️ Configuration

Supply your Hevy API key via the HEVY_API_KEY environment variable (in .env or system environment).

⚠️ CLI API key arguments (--hevy-api-key=..., --hevyApiKey=..., hevy-api-key=...) are still accepted for backward compatibility, but are deprecated and insecure. Use HEVY_API_KEY instead.

Set HEVY_MCP_API_TIMEOUT to override the default 30-second Hevy API request timeout. Its value is in milliseconds.

Set HEVY_MCP_DEBUG=1 to emit verbose, privacy-bounded diagnostics to stderr. Debug records include tool invocations and sanitized Hevy API response timing and status details. Other values leave diagnostics disabled, and stdout remains reserved for the MCP JSON-RPC stream.

# Example .env
HEVY_API_KEY=your_hevy_api_key_here
# Optional: customize Hevy API request timeout (milliseconds)
HEVY_MCP_API_TIMEOUT=30000
# Optional: enable verbose stderr diagnostics (only the value 1 enables it)
HEVY_MCP_DEBUG=1

🧠 Exercise Template Cache Behavior

search-exercise-templates and the hevy://exercise-templates resource use a shared in-memory async cache for the full exercise template catalog:

• TTL: 5 minutes per cached catalog entry.
• Memory bound: max 1 catalog entry (LRU bounded cache).
• In-flight de-duplication: concurrent requests share the same active fetch when possible.
• Manual refresh: set refresh: true in the tool input to invalidate the cached catalog and force a re-fetch from the Hevy API.

Paginated get-exercise-templates requests still call the API directly to keep paging behavior explicit and avoid cross-page invalidation complexity.

📡 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. Recent observability changes also add:

• lifecycle spans around server build, run, and stdio connect
• per-tool execution spans plus captured handler exceptions
• stdio parse diagnostics, including leading UTF-8 BOM stripping and invalid JSON context
• a deterministic pseudonymous Sentry user ID derived from HEVY_API_KEY, so the raw key is never sent to Sentry

As of v1.18.0, hevy-mcp removed HTTP/SSE transport and its previous Docker packaging. Docker support is now available again for the stdio server.

Both npx hevy-mcp and the official container image use stdio; HTTP ports and detached-container deployment are not supported.

🛠️ Available MCP Tools