hevy-mcp-server

MCP-сервер для API отслеживания тренировок Hevy. Даёт LLM доступ на чтение и запись к тренировкам, программам, шаблонам упражнений, истории по каждому упражнению и измерениям тела.

Покрывает все 15 конечных точек публичного API Hevy (v0.0.1) в 27 инструментах.

Требования

• Node.js 18+

• Подписка Hevy Pro — доступ к API только для Pro

• Ключ API с https://hevy.com/settings?developer

Related MCP server: hevy-mcp-server

Установка

pnpm install
pnpm run build

Настройка

Укажите HEVY_API_KEY в конфигурации вашего MCP-клиента. Для Claude Desktop — в claude_desktop_config.json:

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp-server/dist/index.js"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

Удалённый/HTTP-режим, локально:

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

Интерактивный просмотр инструментов:

HEVY_API_KEY=your-key pnpm run inspect

Развёртывание (для мобильных Claude / коннекторов claude.ai)

Claude подключается к пользовательским коннекторам из облака Anthropic, а не с вашего устройства, поэтому для мобильных и claude.ai этот сервер должен быть доступен по публичному HTTPS. Claude Code и Claude Desktop — нет, используйте там stdio.

1. Сгенерируйте секрет пути

openssl rand -hex 32

Сервер отказывается запускаться на не-loopback интерфейсе без установленного MCP_PATH_SECRET, потому что публичная конечная точка с вашим ключом Hevy — это открытый прокси к вашему аккаунту. С установленным секретом конечная точка перемещается на /mcp/<secret>, и любой другой путь возвращает 404 — включая неверный секрет, так что сканирование хоста не раскрывает, что там живёт MCP-сервер.

2. Разверните

Включённые Dockerfile и railway.json работают как есть на Railway, Render или Fly. Образ устанавливает TRANSPORT=http и HOST=0.0.0.0 и запускается от непривилегированного пользователя. Задайте две переменные в панели платформы:

PORT внедряется платформой. /healthz — неаутентифицированный зонд живости.

3. Проверьте

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. Добавьте коннектор

На claude.ai в браузере — коннекторы нельзя добавить из мобильного приложения:

1. Настройка → Коннекторы → Добавить пользовательский коннектор

2. URL: https://your-app.up.railway.app/mcp/<secret>

3. На телефоне откройте чат и включите его в разделе + → Коннекторы

Относитесь к этому URL как к паролю: это единственное, что отделяет интернет от вашего журнала тренировок. Если он утёк, смените MCP_PATH_SECRET и добавьте коннектор заново.

Инструменты

Тренировки — hevy_list_workouts, hevy_get_workout, hevy_count_workouts, hevy_list_workout_events, hevy_create_workout, hevy_update_workout

Сессии — hevy_start_session, hevy_get_active_session, hevy_finish_session, hevy_cancel_session

Программы — hevy_list_routines, hevy_get_routine, hevy_create_routine, hevy_update_routine

Папки программ — hevy_list_routine_folders, hevy_get_routine_folder, hevy_create_routine_folder

Шаблоны упражнений — hevy_search_exercise_templates, hevy_list_exercise_templates, hevy_get_exercise_template, hevy_create_exercise_template

Прогресс — hevy_get_exercise_history, hevy_list_body_measurements, hevy_get_body_measurement, hevy_create_body_measurement, hevy_update_body_measurement

Аккаунт — hevy_get_user_info

Каждый инструмент чтения принимает response_format: "markdown" | "json". Markdown — по умолчанию и оптимизирован для чтения LLM; JSON — полная структурированная полезная нагрузка. structuredContent всегда заполняется независимо от формата.

Примеры

"Что я тренировал на этой неделе?" → hevy_list_workouts с page_size=5. Возвращает названия, длительность, список упражнений и общий объём за сессию.

"Запиши сегодняшний жим: 3x8 на 60 кг" → hevy_search_exercise_templates с query="bench press" для получения id, затем hevy_create_workout с тремя подходами { weight_kg: 60, reps: 8 }.

"Начинаю ноги сейчас" → hevy_start_session с title="Leg Day". Время начала фиксируется на сервере, и сессия отображается в Hevy как выполняемая. Когда закончите, hevy_finish_session с выполненными упражнениями завершит её с реальной длительностью.

"Становлюсь ли я сильнее в приседаниях?" → hevy_search_exercise_templates с query="squat", затем hevy_get_exercise_history с start_date. Возвращает все записанные подходы от новых к старым, плюс лучший подход по оценочному 1ПМ.

Заметки по дизайну

Сначала поиск, потом запись. У Hevy нет серверного поиска упражнений, но каждая запись требует exercise_template_id. hevy_search_exercise_templates перелистывает каталог (до 30 страниц по 100) и фильтрует локально по названию, группе мышц, оборудованию и только пользовательским. Направьте модель сначала на этот инструмент — id невозможно угадать.

Обновления — это замена, а не патчи. hevy_update_workout, hevy_update_routine и hevy_update_body_measurement перезаписывают весь ресурс; всё, что опущено, удаляется или обнуляется. Все три имеют destructiveHint: true, и их описания говорят модели сначала прочитать текущее состояние. Это единственные три разрушительных инструмента — у API Hevy нет конечных точек удаления.

Живые сессии — это соглашение о названии, а не состояние сервера. У API Hevy нет конечной точки начала тренировки и он не может управлять таймером в приложении, поэтому hevy_start_session создаёт реальную тренировку заранее с названием 🔴 In Progress — <title>, а hevy_finish_session переписывает её с фактическим временем окончания. Этот маркер — единственный сохраняющийся дескриптор: сервер не хранит состояние между запросами, поэтому любой чат на любом устройстве находит открытую сессию, сканируя последние тренировки. Цена — незавершённая сессия остаётся видимой в журнале, и поскольку Hevy не предоставляет удаления, hevy_cancel_session может только переименовать её, но не удалить.

Всё в килограммах. В API нет поля единиц измерения. Поля ввода называются weight_kg, чтобы не было неоднозначности в том, что отправляет модель, а вывод в markdown отображает оба значения (60 kg (132.3 lb)), чтобы читатель из США не переводил в уме.

Ограничения размера страницы применяются на стороне клиента. Hevy возвращает голый 400 для слишком большой страницы. Схемы Zod ограничивают каждую конечную точку её документированным лимитом (10 для большинства, 100 для шаблонов упражнений), поэтому модель получает точное сообщение вместо неудачного запроса.

Ошибки приводят к следующим действиям. 404 называет инструмент, который создаёт допустимые id для этого ресурса. 409 при измерении тела указывает на инструмент обновления. 403 объясняет, что доступ к API требует Pro.

Либеральные выходные схемы. Документация Hevy предупреждает, что этот API 0.0.1 может менять структуру без уведомления. Выходные схемы используют passthrough() с необязательными полями, чтобы добавление поля на стороне API не превращалось в жёсткий сбой инструмента.

Структура проекта

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

Предостережения

• API Hevy официально имеет версию 0.0.1, и его собственная документация предупреждает, что структура может измениться или быть заброшена.

• Папку программы нельзя изменить после создания — конечная точка обновления не принимает folder_id.

• Фильтрация по оборудованию в поиске сопоставляется с названием упражнения, поскольку API не предоставляет оборудование как поле в шаблонах.

• hevy_create_exercise_template возвращает числовой id, в отличие от строковых id, используемых везде в API.

Тесты

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

Оба набора тестов запускаются против локального мока, поэтому не нужны ни ключ API, ни доступ к сети.