# Minimal Hevy MCP

A small local Model Context Protocol server that lets an agent read Hevy workout
data and create workout routines through Hevy's public API.

## Included tools

- `hevy_list_workouts`
- `hevy_get_workout`
- `hevy_list_routines`
- `hevy_get_routine`
- `hevy_search_exercises`
- `hevy_get_exercise_history`
- `hevy_create_workout`
- `hevy_create_routine`

The first six tools are read-only. `hevy_create_workout` and
`hevy_create_routine` write to the connected Hevy account and are annotated as
non-idempotent mutations.

`hevy_create_routine` creates a reusable plan for a future session.
`hevy_create_workout` logs an already-completed session using actual start/end
times and set results. It defaults completed workouts to private and rejects sets
without a recorded performance metric.

## Requirements

- Node.js 20 or newer
- A Hevy Pro account and API key from <https://hevy.com/settings?developer>

## Install and validate

```bash
npm install
npm run check
npm run build
npm run smoke
```

## Run locally

```bash
export HEVY_API_KEY="your-key"
npm start
```

The server communicates over stdin/stdout, so it will appear to wait silently
when run directly. An MCP host is expected to start it and communicate with it.

## Add it to Codex

Build the server first, make `HEVY_API_KEY` available to the environment that
starts Codex, then run:

```bash
codex mcp add hevy -- node /absolute/path/to/hevy-mcp/dist/index.js
```

Restart Codex after adding the server. Verify the configuration with:

```bash
codex mcp list
```

Do not commit the API key or pass it as a tool argument. The MCP reads it only
from `HEVY_API_KEY` and sends it to Hevy in the required `api-key` header.

## Suggested first request

> Read my five most recent workouts and summarize frequency, exercise selection,
> and obvious progression patterns. Do not create or update anything.

When asking the agent to create a routine, require it to show the full routine
and get your approval before calling `hevy_create_routine`.

When logging a completed workout, give the agent the actual exercises, set
results, and times. Require it to show the complete workout and get your approval
before calling `hevy_create_workout`. The agent must never invent completed
results.