Content
# hevy-mcp: Model Context Protocol Server for Hevy Fitness API
[](https://smithery.ai/server/@chrisdoc/hevy-mcp)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server implementation that interfaces with the [Hevy fitness tracking app](https://www.hevyapp.com/) and its [API](https://api.hevyapp.com/docs/). 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.
## Prerequisites
- Node.js (v20 or higher)
- pnpm (via Corepack)
- A Hevy API key
## Installation
### Run via npx (recommended)
You can launch the server directly without cloning:
```bash
HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp
```
### Manual Installation
```bash
# Clone the repository
git clone https://github.com/chrisdoc/hevy-mcp.git
cd hevy-mcp
# Install dependencies
corepack use pnpm@10.22.0
cp .env.sample .env
# Edit .env and add your Hevy API key
```
### Integration with Cursor
To use this MCP server with Cursor, you need to update your `~/.cursor/mcp.json` file by adding the following configuration:
```json
{
"hevy-mcp-server": {
"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.
## Configuration
You can supply your Hevy API key in two ways:
1. Environment variable (`HEVY_API_KEY`)
2. Command-line argument (`--hevy-api-key=your_key` or `hevy-api-key=your_key` after `--` when using pnpm scripts)
Create a `.env` file in the project root (you can copy from [.env.sample](.env.sample)) with the following content if using the environment variable approach:
```env
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:
```bash
pnpm start -- --hevy-api-key=your_hevy_api_key_here
```
## 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`.
1. Ensure dependencies are installed: `pnpm install`
2. Launch the Smithery playground locally:
```bash
pnpm run smithery:dev
```
The CLI will prompt for `HEVY_API_KEY`, invoke `createServer({ config })`, and open the Smithery MCP playground.
3. Build the deployable bundle:
```bash
pnpm run smithery:build
```
4. 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.yaml` env mapping is required.
hevy-mcp now runs exclusively over stdio, which works seamlessly with MCP-aware clients like Claude Desktop and Cursor. HTTP transport has been removed to simplify deployment.
## Usage
### Development
```bash
pnpm run dev
```
This starts the MCP server in development mode with hot reloading.
### Production
```bash
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 data
- `get-workout`: Get a single workout by ID
- `create-workout`: Create a new workout
- `update-workout`: Update an existing workout
- `get-workout-count`: Get the total count of workouts
- `get-workout-events`: Get workout update/delete events
### Routine Tools
- `get-routines`: Fetch and format routine data
- `create-routine`: Create a new routine
- `update-routine`: Update an existing routine
- `get-routine-by-id`: Get a single routine by ID using direct endpoint
### Exercise Template Tools
- `get-exercise-templates`: Fetch exercise templates
- `get-exercise-template`: Get a template by ID
### Routine Folder Tools
- `get-routine-folders`: Fetch routine folders
- `create-routine-folder`: Create a new folder
- `get-routine-folder`: Get a folder by ID
### Webhook Tools
- `get-webhook-subscription`: Get the current webhook subscription
- `create-webhook-subscription`: Create a new webhook subscription
- `delete-webhook-subscription`: Delete the current webhook subscription
## Project Structure
```plaintext
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
│ ├── formatters.ts # Data formatting helpers
│ └── validators.ts # Input validation helpers
├── 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:
```bash
pnpm run check
```
### Testing
#### Run All Tests
To run all tests (unit and integration), use:
```bash
pnpm test
```
> **Note:** If the `HEVY_API_KEY` environment variable is set, integration tests will also run. If not, only unit tests will run.
#### Run Only Unit Tests
To run only unit tests (excluding integration tests):
```bash
pnpm vitest run --exclude tests/integration/**
```
Or with coverage:
```bash
pnpm vitest run --coverage --exclude tests/integration/**
```
#### Run Only Integration Tests
To run only the integration tests (requires a valid `HEVY_API_KEY`):
```bash
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:
1. Unit tests will always run on every push and pull request
2. Integration tests will only run if the `HEVY_API_KEY` secret is set in the repository settings
To set up the `HEVY_API_KEY` secret:
1. Go to your GitHub repository
2. Click on "Settings" > "Secrets and variables" > "Actions"
3. Click on "New repository secret"
4. Set the name to `HEVY_API_KEY` and the value to your Hevy API key
5. Click "Add secret"
If the secret is not set, the integration tests step will be skipped with a message indicating that the API key is missing.
### Generating API Client
The API client is generated from the OpenAPI specification using [Kubb](https://kubb.dev/):
```bash
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 variable `ROLLUP_SKIP_NODEJS_NATIVE_BUILD=true` before running `pnpm run build`. This forces Rollup to use the pure JavaScript fallback and avoids the npm optional dependency bug on some Linux runners.
## License
This project is licensed under the MIT License - see the [LICENSE](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](https://github.com/modelcontextprotocol) for the MCP SDK
- [Hevy](https://www.hevyapp.com/) for their fitness tracking platform and API
