🏁 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:

1. Environment Variable: HEVY_API_KEY (in .env or system environment).
2. 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.

Stdio Only

As of version 1.18.0, hevy-mcp only supports stdio transport. HTTP/SSE transport has been completely removed to simplify the codebase and focus on the native MCP experience.

Docker

Docker-based workflows are retired. The provided Dockerfile now exits with a message pointing to the stdio-native experience. Legacy GHCR images are no longer updated.

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