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 to access and manage workout data, routines, exercise templates, and more through the Hevy API (requires PRO subscription).
Features
- Workout Management: Fetch, create, and update workouts
- Routine Management: Access and manage workout routines
- Exercise Templates: Browse available exercise templates
- Folder Organization: Manage routine folders
- Webhook Subscriptions: Create, view, and delete webhook subscriptions for workout events
Note: HTTP transport and Docker images remain deprecated. Smithery deployment now uses the official TypeScript runtime flow (no Docker required), or you can run the server locally via stdio (e.g.,
npx hevy-mcp). Existing GHCR images remain available but are no longer updated.
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 ≥ 20, Hevy API key |
| Local development | pnpm install && pnpm run dev | .env with HEVY_API_KEY, pnpm via Corepack |
| Smithery playground / deploy | pnpm run smithery:dev / pnpm run smithery:build | HEVY_API_KEY, SMITHERY_API_KEY (or pnpm dlx @smithery/cli login) |
Prerequisites
- Node.js (v20 or higher; strongly recommended to use the exact version pinned in
.nvmrcto match CI) - pnpm (via Corepack)
- A Hevy API key
- Optional: A Smithery account + API key/login if you plan to deploy via Smithery
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
corepack use pnpm@10.22.0
pnpm install
# Create .env and add your keys (never commit real keys)
cp .env.sample .env
# Edit .env and add at least HEVY_API_KEY. Add SMITHERY_API_KEY if you use Smithery CLI.
Integration with Cursor
To use this MCP server with Cursor, add/merge this server entry under
"mcpServers" in ~/.cursor/mcp.json:
{
"hevy-mcp": {
"command": "npx",
"args": ["-y", "hevy-mcp"],
"env": {
"HEVY_API_KEY": "your-api-key-here"
}
}
}
Make sure to replace your-api-key-here with your actual Hevy API key.
If your mcp.json already contains other servers, do not replace the whole
file—merge the "hevy-mcp" entry into your existing "mcpServers" object.
The "hevy-mcp" key name is arbitrary. If you already have an existing config
using a different name (for example "hevy-mcp-server"), you can keep it.
If you already have an existing "mcpServers" object, merge the "hevy-mcp"
entry into it without removing other servers.
Example full ~/.cursor/mcp.json
{
"mcpServers": {
"hevy-mcp": {
"command": "npx",
"args": ["-y", "hevy-mcp"],
"env": {
"HEVY_API_KEY": "your-api-key-here"
}
}
}
}
Configuration
You can supply your Hevy API key in two ways:
- Environment variable (
HEVY_API_KEY) - Command-line argument (
--hevy-api-key=your_keyorhevy-api-key=your_keyafter--when using pnpm scripts)
Create a .env file in the project root (you can copy from .env.sample) with the following content if using the environment variable approach:
HEVY_API_KEY=your_hevy_api_key_here
Replace your_hevy_api_key_here with your actual Hevy API key. If you prefer the command argument approach you can skip setting the environment variable and start the server with for example:
pnpm start -- --hevy-api-key=your_hevy_api_key_here
Sentry monitoring
hevy-mcp ships with Sentry monitoring baked into the built MCP server so
that usage and errors from published builds can be observed.
The server initializes @sentry/node with a fixed DSN, release name derived
from the package version, and tracing settings
directly in the code (see src/index.ts), and wraps the underlying
McpServer with Sentry.wrapMcpServerWithSentry so requests and tool calls
are captured by Sentry automatically. The configuration uses
sendDefaultPii: false to keep Sentry's default PII collection disabled.
There is currently no built-in toggle to disable Sentry for the published
package. If you need a build without Sentry telemetry, you can fork the
repository and remove the Sentry initialization in src/index.ts.
Transport
Deploy via Smithery (TypeScript runtime)
Smithery can bundle and host hevy-mcp without Docker by importing the exported createServer and configSchema from src/index.ts.
-
Ensure dependencies are installed:
pnpm install -
Launch the Smithery playground locally:
pnpm run smithery:devThe CLI will prompt for
HEVY_API_KEY, invokecreateServer({ config }), and open the Smithery MCP playground. -
Build the deployable bundle:
pnpm run smithery:build -
Connect the repository to Smithery and trigger a deployment from their dashboard. Configuration is handled entirely through the exported Zod schema, so no additional
smithery.yamlenv mapping is required.
Why are
chalk,cors, and@smithery/sdkdependencies? Smithery’s TypeScript runtime injects its own Express bootstrap that imports these packages. Declaring them inpackage.jsonensures the Smithery CLI can bundle your server successfully.
Stdio Only (Current)
As of version 1.18.0, hevy-mcp only supports stdio transport. HTTP/SSE transport has been completely removed.
hevy-mcp runs exclusively over stdio, which works seamlessly with MCP-aware clients like Claude Desktop and Cursor. The server communicates via standard input/output streams using JSON-RPC messages.
Migration from HTTP/SSE Transport
If you were using HTTP or SSE transport in an older version (< 1.18.0), you must migrate to stdio.
The HTTP/SSE transport was removed in v1.18.0 to simplify the codebase and focus on the stdio-native MCP experience. If you're encountering errors like:
"stream is not readable"when making HTTP requests"HTTP transport mode has been removed from hevy-mcp"- Server messages about SSE mode on
http://localhost:3001
You are likely running an outdated build or trying to connect with an HTTP-based client. Here's how to fix it:
Steps to Migrate:
-
Update to the latest version:
npx -y hevy-mcp@latest # or if installed locally: pnpm install hevy-mcp@latest -
Update your client configuration to use stdio transport instead of HTTP. For example, in Cursor's
~/.cursor/mcp.json:Old HTTP-based config (no longer supported):
{ "hevy-mcp": { "url": "http://localhost:3001/sse" } }New stdio-based config (current):
{ "hevy-mcp": { "command": "npx", "args": ["-y", "hevy-mcp"], "env": { "HEVY_API_KEY": "your-api-key-here" } } } -
Clear any cached builds:
# If you have a local clone, rebuild pnpm run build # Or remove node_modules and reinstall rm -rf node_modules dist pnpm install pnpm run build -
Ensure you're not running a custom HTTP server. If you have custom code that imports
createHttpServer(), it will now throw an error. Remove those imports and use stdio transport instead.
If you absolutely need HTTP/SSE transport, you can use version 1.17.x or earlier, but those versions are no longer maintained and contain known bugs (including the "stream is not readable" issue caused by middleware conflicts).
Usage
Development
pnpm run dev
This starts the MCP server in development mode with hot reloading.
Production
pnpm run build
pnpm start
Docker (deprecated)
Docker-based workflows have been retired so we can focus on the stdio-native experience. The bundled Dockerfile now exits with a clear message to prevent accidental builds, and .dockerignore simply documents the deprecation. Previously published images remain available on GHCR (for example ghcr.io/chrisdoc/hevy-mcp:latest), but they are no longer updated. For the best experience, run the server locally via npx hevy-mcp or your own Node.js runtime.
Available MCP Tools
The server implements the following MCP tools for interacting with the Hevy API:
Workout Tools
get-workouts: Fetch and format workout dataget-workout: Get a single workout by IDcreate-workout: Create a new workoutupdate-workout: Update an existing workoutget-workout-count: Get the total count of workoutsget-workout-events: Get workout update/delete events
Routine Tools
get-routines: Fetch and format routine datacreate-routine: Create a new routineupdate-routine: Update an existing routineget-routine-by-id: Get a single routine by ID using direct endpoint
Exercise Template Tools
get-exercise-templates: Fetch exercise templatesget-exercise-template: Get a template by ID
Routine Folder Tools
get-routine-folders: Fetch routine folderscreate-routine-folder: Create a new folderget-routine-folder: Get a folder by ID
Webhook Tools
get-webhook-subscription: Get the current webhook subscriptioncreate-webhook-subscription: Create a new webhook subscriptiondelete-webhook-subscription: Delete the current webhook subscription
Project Structure
hevy-mcp/
├── .env # Environment variables (API keys)
├── src/
│ ├── index.ts # Main entry point
│ ├── tools/ # Directory for MCP tool implementations
│ │ ├── workouts.ts # Workout-related tools
│ │ ├── routines.ts # Routine-related tools
│ │ ├── templates.ts # Exercise template tools
│ │ ├── folders.ts # Routine folder tools
│ │ └── webhooks.ts # Webhook subscription tools
│ ├── generated/ # API client (generated code)
│ │ ├── client/ # Kubb-generated client
│ │ │ ├── api/ # API client methods
│ │ │ ├── types/ # TypeScript types
│ │ │ ├── schemas/ # Zod schemas
│ │ │ └── mocks/ # Mock data
│ └── utils/ # Helper utilities
│ ├── config.ts # Env/CLI config parsing
│ ├── error-handler.ts # Tool error wrapper + response builder
│ ├── formatters.ts # Domain formatting helpers
│ ├── hevyClient.ts # API client factory
│ ├── httpServer.ts # Legacy HTTP transport (deprecated; throws explicit error; kept only for backward compatibility - removing may be breaking)
│ ├── response-formatter.ts # MCP response utilities
│ └── tool-helpers.ts # Zod schema -> TS type inference
├── scripts/ # Build and utility scripts
└── tests/ # Test suite
├── integration/ # Integration tests with real API
│ └── hevy-mcp.integration.test.ts # MCP server integration tests
Development Guide
Code Style
This project uses Biome for code formatting and linting:
pnpm run check
Testing
Run All Tests
To run all tests (unit and integration), use:
pnpm test
Note:
pnpm testruns all tests. Integration tests will fail by design ifHEVY_API_KEYis missing. If you don’t have an API key locally, use the unit test command below.
Run Only Unit Tests
To run only unit tests (excluding integration tests):
pnpm vitest run --exclude tests/integration/**
Or with coverage:
pnpm vitest run --coverage --exclude tests/integration/**
Run Only Integration Tests
To run only the integration tests (requires a valid HEVY_API_KEY):
pnpm vitest run tests/integration
Note: The integration tests will fail if the HEVY_API_KEY environment variable is not set. This is by design to ensure that the tests are always run with a valid API key.
GitHub Actions Configuration
For GitHub Actions:
- Unit + integration tests are executed as part of the normal
Build and Testworkflow - Integration tests require the
HEVY_API_KEYsecret to be set
The workflow runs pnpm vitest run --coverage and provides HEVY_API_KEY from
repository secrets.
To set up the HEVY_API_KEY secret:
- Go to your GitHub repository
- Click on "Settings" > "Secrets and variables" > "Actions"
- Click on "New repository secret"
- Set the name to
HEVY_API_KEYand the value to your Hevy API key - Click "Add secret"
If the secret is not set, the integration tests will fail (by design).
To set up Sentry secrets for source map uploads during builds:
The build process uses Sentry's Rollup plugin to upload source maps. You need to configure three secrets:
-
Go to your GitHub repository
-
Click on "Settings" > "Secrets and variables" > "Actions"
-
Add the following secrets:
SENTRY_ORG: Your Sentry organization slugSENTRY_PROJECT: Your Sentry project slugSENTRY_AUTH_TOKEN: A Sentry auth token withproject:releasesscope
You can create a Sentry auth token at: https://sentry.io/settings/account/api/auth-tokens/
If these secrets are not set, the build will still succeed, but source maps will not be uploaded to Sentry.
Note: GitHub does not provide secrets to pull requests from forks by default, so
fork PRs may fail CI unless a maintainer reruns the checks with HEVY_API_KEY
available.
If CI is failing only because the fork PR is missing HEVY_API_KEY, that is
expected; maintainers may rerun the workflow with secrets enabled.
For contributors from forks: CI failures caused solely by missing HEVY_API_KEY
do not indicate a problem with your changes.
All other CI checks (build, formatting/linting, unit tests, etc.) are still expected to pass.
Only failures caused solely by missing HEVY_API_KEY on forked PRs are
considered acceptable.
Generating API Client
The API client is generated from the OpenAPI specification using Kubb:
pnpm run export-specs
pnpm run build:client
Kubb generates TypeScript types, API clients, Zod schemas, and mock data from the OpenAPI specification.
Troubleshooting
- Rollup optional dependency missing: If you see an error similar to
Cannot find module @rollup/rollup-linux-x64-gnu, set the environment variableROLLUP_SKIP_NODEJS_NATIVE_BUILD=truebefore runningpnpm run build. This forces Rollup to use the pure JavaScript fallback and avoids the npm optional dependency bug on some Linux runners.
Troubleshooting Smithery deployments
smithery.yamlvalidation failed (unexpected fields): Onlyruntime,target, andenvare allowed for the TypeScript runtime. Removeentry,name, or other fields.Could not resolve "chalk"/"cors": Runpnpm installso the runtime dependencies listed inpackage.jsonare present before invoking Smithery.Failed to connect to Smithery API: Unauthorized: Log in viapnpm dlx @smithery/cli loginor setSMITHERY_API_KEYin.env.- Tunnel crashes with
RangeError: Invalid count value: This is a known issue in certain@smithery/clibuilds. Upgrade/downgrade the CLI (e.g.,pnpm add -D @smithery/cli@latest) or contact Smithery support.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Acknowledgements
- Model Context Protocol for the MCP SDK
- Hevy for their fitness tracking platform and API