# hevy-mcp

A Python [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Hevy](https://hevy.com) fitness app API. Gives Claude (or any MCP-compatible AI) full access to your Hevy workout data — log workouts, manage routines, track body measurements, and more.

## Features

- **25 tools** covering every endpoint of the [Hevy API](https://api.hevyapp.com/docs/)
- **No build step** — pure Python, just install and run
- **Full CRUD** — create, read, update workouts, routines, exercise templates, folders, measurements, and webhooks

## Tools

| Category | Tools |
|---|---|
| User | `get_user_info` |
| Workouts | `get_workouts`, `get_workout`, `get_workout_count`, `get_workout_events`, `create_workout`, `update_workout` |
| Routines | `get_routines`, `get_routine`, `create_routine`, `update_routine` |
| Routine Folders | `get_routine_folders`, `get_routine_folder`, `create_routine_folder` |
| Exercise Templates | `get_exercise_templates`, `get_exercise_template`, `create_exercise_template` |
| Exercise History | `get_exercise_history` |
| Body Measurements | `get_body_measurements`, `get_body_measurement`, `create_body_measurement`, `update_body_measurement` |
| Webhooks | `get_webhooks`, `create_webhook`, `delete_webhook` |

## Requirements

- Python 3.12+
- Hevy Pro account (required for API access)
- API key from [hevy.com/settings?developer](https://hevy.com/settings?developer)

## Installation

```bash
git clone https://github.com/srdjancodes/hevy-mcp
cd hevy-mcp
pip install -r requirements.txt
```

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hevy": {
      "command": "python",
      "args": ["/absolute/path/to/hevy-mcp/server.py"],
      "env": {
        "HEVY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see the Hevy server listed under the tools icon in the chat.

### Environment variable

Alternatively, set `HEVY_API_KEY` in your environment and run directly:

```bash
export HEVY_API_KEY=your-api-key-here
python server.py
```

## Usage examples

Once connected, you can ask Claude things like:

- *"Show me my last 5 workouts"*
- *"Log a chest workout I did today — bench press 3x8 at 100kg, incline dumbbell 3x10 at 30kg"*
- *"Create a Push/Pull/Legs routine"*
- *"What's my body weight trend over the last month?"*
- *"Find the exercise template ID for Romanian deadlift"*
- *"Show me all my bench press sets from the last 3 months"*

## Tech stack

- [FastMCP](https://github.com/jlowin/fastmcp) — Python MCP server framework
- [httpx](https://www.python-httpx.org/) — HTTP client
- [Hevy API](https://api.hevyapp.com/docs/) — official REST API

## License

MIT