# Hevy MCP — Official API, local credentials

A local Model Context Protocol server that connects agents directly to the [official Hevy Public API](https://api.hevyapp.com/docs/). It does not depend on a community Hevy SDK or proxy service.

It exposes 22 tools for workouts, routines, exercise templates and history, routine folders, body measurements, and account information. Reads are enabled by default. Writes require a server-level opt-in plus a confirmation field on every call.

> Hevy currently limits its Public API to Hevy Pro users and labels the API as an early release. Generate a key at [Hevy Developer Settings](https://hevy.com/settings?developer).

## Quick start for Codex on macOS

Requirements: Node.js 20 or newer, Git, and the Codex CLI.

```sh
git clone https://github.com/andywangyzfh/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build
npm run setup-key
npm run install:codex
```

`setup-key` hides your input and saves the key in macOS Keychain under `codex-hevy-api-key`. The key is not written to this repository or to the Codex configuration. Restart Codex or open a new task after registration.

Prefer a macOS dialog? Run:

```sh
zsh scripts/setup-key-gui.zsh
```

To register with confirmed write support:

```sh
zsh scripts/install-codex.zsh --allow-writes
```

## Other MCP hosts and operating systems

Build the server first:

```sh
npm ci
npm run build
```

Start it with `node /absolute/path/to/hevy-mcp/dist/index.js`. Supply the API key using one of these methods:

1. `HEVY_API_KEY` — direct environment variable.
2. `HEVY_API_KEY_FILE` — absolute path to a file containing only the key.
3. macOS Keychain — automatic fallback using service `codex-hevy-api-key`.

Generic MCP host configuration:

```json
{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp/dist/index.js"],
      "env": {
        "HEVY_API_KEY_FILE": "/absolute/path/to/a/private/hevy-api-key"
      }
    }
  }
}
```

Keep the key file outside the repository and restrict it to the current user. See [docs/SETUP.md](docs/SETUP.md) for platform-specific setup and troubleshooting.

## Write protection

The server starts read-only. Set `HEVY_MCP_ALLOW_WRITES=1` for the MCP process to permit mutations. Create tools also require `confirm=true`; full replacement tools require `confirm_full_overwrite=true`.

Hevy's PUT endpoints replace the complete workout, routine, or measurement. An agent should always fetch the current object, preserve every intended field, present the proposed result, and only then call a replacement tool.

There are no delete tools because the official Public API does not expose delete endpoints.

## Tools

Read tools cover:

- User information and workout count
- Paginated workouts, individual workouts, and workout change events
- Paginated routines and individual routines
- Exercise template browsing, local title search, and exercise history
- Routine folders
- Body measurements

Write tools cover:

- Create or fully replace a workout
- Create or fully replace a routine
- Create a custom exercise template or routine folder
- Create or fully replace a body measurement

The complete tool reference is in [docs/TOOLS.md](docs/TOOLS.md).

## Give this to an agent

Use the ready-made prompt in [docs/AGENT_INSTALL_PROMPT.md](docs/AGENT_INSTALL_PROMPT.md). It tells an agent how to install the server without asking the user to paste an API key into chat.

## Security model

- Credentials are sent only in the `api-key` header to `https://api.hevyapp.com` by default.
- HTTP redirects are disabled so credentials are not forwarded to another origin.
- A custom API base URL requires `HEVY_MCP_TRUST_BASE_URL=1`; plain HTTP is allowed only for loopback tests.
- Error messages redact the configured key.
- `.env`, build output, dependencies, and logs are excluded from Git.

Read [SECURITY.md](SECURITY.md) before changing credential handling.

## Development

```sh
npm run check
npm test
npm run build
```

The test suite covers headers, query handling, pagination, secret redaction, trusted origins, request serialization, MCP tool discovery, and the default write gate.

## 中文说明

这是一个直接连接 Hevy 官方 Public API 的本地 MCP server，不依赖第三方 Hevy SDK 或代理服务。Hevy Pro 用户可以让 Codex 等 MCP agent 读取训练计划、训练记录、动作历史和身体数据；显式开启后也可以创建或完整更新数据。

macOS 最快安装方式是依次运行上面的克隆、`npm ci`、构建、钥匙串设置和 Codex 注册命令。不要把 API key 发到聊天里，也不要提交 `.env`。默认只读；需要写入时使用 `scripts/install-codex.zsh --allow-writes`，并在具体修改前让 agent 展示完整变更内容。