by chrisdoc
Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.
# Add to your Claude Code skills
git clone https://github.com/chrisdoc/hevy-mcpA 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).
No comments yet. Be the first to share your thoughts!
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 |
.nvmrc).You can launch the server directly without cloning:
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp
# 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
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"
}
}
}
}
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"
}
}
}
}
oxlint/oxfmt) for near-instant linting and formatting.Supply your Hevy API key via:
HEVY_API_KEY (in .env or system environment).--hevy-api-key=your_key (after -- in npm scripts).# Example .env
HEVY_API_KEY=your_hevy_api_key_here
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.
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-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.
| 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 |
npm run buildnpm run check (uses oxlint/oxfmt)npx vitest run --exclude tests/integration/**npm test (requires HEVY_API_KEY)For a detailed senior engineer guide, please refer to AGENTS.md.
The API client is automatically generated from the OpenAPI spec using Kubb:
npm run build:client
Contributions are welcome! Please open an issue or PR for any major changes.