# hevy-mcp-server

A complete, open-source single tenant [MCP](https://modelcontextprotocol.io) server for [Hevy](https://www.hevyapp.com)'s [public API](https://api.hevyapp.com/docs/). Every endpoint Hevy exposes is reachable through one of the tools below -- workouts, routines, routine folders, exercise templates (including custom exercises), per-exercise history, and body measurements.

Runs two ways:
- **Locally over stdio** -- for Claude Desktop / Claude Code, zero hosting required.
- **Remotely over HTTP** -- for [claude.ai](https://claude.ai) / Cowork connectors, deployable to Fly.io with the included Dockerfile.

View the full product and technical design [here](PRD-TDD.md).

## Tools

12 tools cover all 21 endpoint paths in Hevy's public API (several are consolidated behind one tool via a `view`/`action` parameter to avoid near-duplicate tools). Full list with exact endpoint coverage: [docs/tools.md](docs/tools.md).

| Read | Write |
|---|---|
| `get_user` | `modify_workouts` |
| `get_workouts` | `modify_routines` |
| `list_routines` | `create_routine_folder` |
| `list_routine_folders` | `create_exercise_template` |
| `list_exercise_templates` | `modify_body_measurement` |
| `get_exercise_history` | |
| `list_body_measurements` | |

## Quick start (local, stdio)

Requires Node.js 20+ and a Hevy Pro subscription. Grab your [Hevy API key](https://hevy.com/settings?developer) first.

```bash
npx hevy-mcp-server
```

Point your MCP client (Claude Desktop, Claude Code, etc.) at it. For Claude Desktop, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["hevy-mcp-server"],
      "env": {
        "HEVY_API_KEY": "your-api-key-here",
        "HEVY_READ_ONLY": "false"
      }
    }
  }
}
```

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `HEVY_API_KEY` | yes | -- | Your Hevy API key (a UUID from https://hevy.com/settings?developer). Never logged, never echoed in tool output. |
| `HEVY_READ_ONLY` | no | `false` | When `true`, every mutation tool is hidden from `tools/list` entirely. Recommended for any instance you don't fully trust the client of. |
| `HEVY_API_BASE_URL` | no | `https://api.hevyapp.com/v1` | Override for testing against a mock server. |

HTTP mode (below) needs three more: `PORT`, `PUBLIC_URL`, `MCP_HTTP_PASSWORD`. See [.env.example](.env.example) for all of them with descriptions.

## Remote (HTTP) deployment on Fly.io

The HTTP transport is gated by OAuth (required for claude.ai/Cowork connector approval). This is **single-tenant OAuth**: there's no concept of separate user accounts, it just gates access to *your* instance behind one shared password. See [docs/architecture.md](docs/architecture.md#oauth) for why and how.

1. Install [flyctl](https://fly.io/docs/flyctl/install/) and `fly auth login`.
2. `fly launch --no-deploy` from this directory (it will read `fly.toml`; rename the `app` there first if you want a specific subdomain).
3. Set secrets (never put these in `fly.toml`, which is committed to git):
   ```bash
   fly secrets set HEVY_API_KEY=your-api-key-here
   fly secrets set MCP_HTTP_PASSWORD=choose-a-strong-password
   ```
4. Edit `fly.toml`'s `PUBLIC_URL` to match your actual `*.fly.dev` hostname (or custom domain), then:
   ```bash
   fly deploy
   ```
5. In claude.ai / Cowork, add a custom connector pointing at `https://<your-app>.fly.dev/mcp`. You'll be redirected to a login page on your own instance -- enter `MCP_HTTP_PASSWORD` to approve the connection.

Notes:
- Single `shared-cpu-1x` machine, no volume. OAuth session state (registered clients, tokens) lives in memory and is lost on redeploy or restart -- you'll just need to reconnect the connector afterwards. Acceptable trade-off for a low-traffic personal instance; see the TDD.
- `fly.toml`'s `[http_service]` is configured to stay always-on (not scaled to zero) for exactly that reason -- a stop/start cycle would otherwise force reconnection too.
- Hevy's docs ask that scheduled/automated syncs avoid firing exactly on the hour -- stagger any cron-style usage by a random minute.

## Development

```bash
npm install
npm run dev:stdio      # run src/stdio.ts directly with tsx
npm run dev:http       # run src/http.ts directly with tsx
npm run typecheck
npm run lint            # biome check
npm run lint:fix
npm test
npm run build           # bundles dist/stdio.js and dist/http.js with tsup
```

See [docs/architecture.md](docs/architecture.md) for the repo layout and request-flow details.

## Skills

[skills/](skills/README.md) bundles ready-made agent workflows on top of these tools (workout logging, routine building, progress reviews, etc.) -- see that folder's README for the full index.

## License

MIT -- see [LICENSE](LICENSE).