hevy-mcp

Подключите Claude к своему журналу тренировок Hevy.

hevy-mcp — это сервер протокола контекста модели (MCP), который позволяет Claude (в приложении для рабочего стола или на сайте claude.ai) просматривать ваши тренировки, составлять новые программы, сохранять их в библиотеку Hevy и анализировать тенденции ваших тренировок — это тот же уровень доступа, который получают пользователи ChatGPT через официальную интеграцию Hevy.

You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
      I've trained least over the last 30 days, and save it in a folder called
      'Hypertrophy Block 1'."

Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
        ✓ created folder "Hypertrophy Block 1"
        ✓ resolved 22 exercises against Hevy's library
        ✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
        Open the Hevy app to start any of them.

Что можно попросить сделать Claude

• Оглянуться назад — «Покажи мои последние 10 тренировок и скажи, какие группы мышц я обделял вниманием».

• Планировать вперед — «Основываясь на моей истории жима лежа, какой рабочий вес будет оптимальным на завтра?»

• Составлять программы — «Составь мне 4-дневный сплит на гипертрофию (верх/низ) и сохрани его».

• Редактировать программы — «В программе 'День жима А' замени жим гантелей на жим штанги стоя, 4 подхода по 5 повторений».

• Анализировать — «Оцени мой одноповторный максимум (1ПМ) в основных упражнениях и построй график прогресса в приседаниях за последние 90 дней».

Требования

• Подписка Hevy PRO (требуется для API разработчика).

• Ваш API-ключ Hevy — получите его на странице https://hevy.com/settings?developer.

• Python 3.11+ или Docker.

• Claude Desktop или рабочее пространство claude.ai, поддерживающее пользовательские коннекторы.

Быстрый старт — Claude Desktop (5 минут)

1. Установка

# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp

# Or with pipx:
pipx install hevy-mcp

# Or with plain pip:
python -m pip install hevy-mcp

2. Добавление в Claude Desktop

Откройте файл конфигурации Claude Desktop:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• Linux — ~/.config/Claude/claude_desktop_config.json

Добавьте запись hevy в раздел mcpServers (создайте файл, если он не существует):

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_paste_your_key_here"
      }
    }
  }
}

Если hevy-mcp отсутствует в вашем PATH (иногда инструменты, установленные через uv, не подхватываются лаунчером Claude Desktop), используйте абсолютный путь, который можно узнать командой which hevy-mcp — например, /Users/you/.local/bin/hevy-mcp.

3. Перезапуск Claude Desktop

Полностью закройте приложение (⌘Q на macOS) и откройте снова. Вы должны увидеть индикатор инструментов, показывающий, что сервер hevy подключен.

4. Попробуйте

«Используй инструмент hevy, чтобы получить мои последние 3 тренировки и сделать их краткий обзор».

Если Claude покажет ваши реальные тренировки, значит, всё готово. 🎉

Альтернатива — claude.ai (удаленный коннектор)

Если вы используете claude.ai в браузере вместо Claude Desktop, запустите hevy-mcp как HTTP-сервис и добавьте его в качестве пользовательского коннектора.

1. Запустите сервер там, где есть HTTPS

Самый простой путь — Docker на Fly.io / Render / Railway:

docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcp

Или напрямую через CLI:

hevy-mcp --http --host 0.0.0.0 --port 8000

Эндпоинт MCP находится по адресу /mcp.

2. Добавьте его как пользовательский коннектор

В claude.ai перейдите в Settings → Connectors → Add custom connector и используйте ваш публичный HTTPS URL, заканчивающийся на /mcp (например, https://hevy-mcp.fly.dev/mcp).

Примечание для нескольких пользователей

Если один и тот же деплой будут использовать несколько человек, не вшивайте HEVY_API_KEY в переменные окружения контейнера — вместо этого передавайте его в заголовке каждого запроса. Сервер считывает X-Hevy-Api-Key, если он присутствует, и использует его вместо переменной окружения. Обычно для этого перед сервером ставится небольшой обратный прокси-сервер (Cloudflare Worker, Nginx), внедряющий аутентификацию.

Что он умеет (полный список инструментов)

Технические особенности:

• Умное кэширование — библиотека упражнений загружается один раз и кэшируется на 24 часа; нечеткий поиск выполняется в оперативной памяти.

• Учет ограничений частоты запросов — делает паузу при получении 429 ошибки и учитывает Retry-After.

• Идемпотентная запись — при создании программы с дублирующимся названием в той же папке Claude попросит подтверждение перед созданием копии.

• Ошибки, понятные для LLM — каждая ошибка возвращается в формате { error, hint }. Подсказка (hint) предлагает следующий конкретный вызов инструмента.

• Никогда не логирует ваш API-ключ.

Устранение неполадок

Самая частая причина: command в claude_desktop_config.json отсутствует в PATH лаунчера. Замените "command": "hevy-mcp" на абсолютный путь, полученный через which hevy-mcp (или where hevy-mcp в Windows). Перезапустите Claude Desktop.

• Проверьте, что вы вставили ключ в блок env (а не в блок args).

• Убедитесь, что ваша подписка Hevy PRO активна.

• Обновите ключ на странице https://hevy.com/settings?developer и попробуйте снова.

search_exercise_templates использует нечеткий поиск, но это не магия. Если Claude выбирает не то упражнение, попросите его «поискать снова с более точным названием» или передайте фильтр equipment (например, «штанга»).

Библиотека упражнений загружается при первом поиске (единоразово, ~200 мс). Все последующие вызовы используют кэш в памяти. Кэш живет 24 часа.

Разработка

git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev          # creates .venv and installs deps
pytest -q                    # offline tests (no real API needed)

# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py

# Stdio (Claude Desktop):
hevy-mcp

# HTTP (claude.ai):
hevy-mcp --http --port 8000

Более подробную информацию см. в CONTRIBUTING.md.

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

hevy-mcp/
├── src/hevy_mcp/
│   ├── server.py        # transport bootstrap (stdio + streamable-http)
│   ├── hevy_client.py   # async httpx client w/ retries & error mapping
│   ├── schemas.py       # Pydantic models
│   ├── cache.py         # 24-hour TTL cache
│   ├── errors.py        # HevyApiError + tool_guard
│   ├── formatters.py    # JSON → readable text
│   └── tools/           # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── Dockerfile

Релизы

См. CHANGELOG.md. Релизы с тегами автоматически публикуются в PyPI.

Лицензия

MIT.

Благодарности

Дизайн этого проекта опирается на идеи двух предыдущих сообществ: chrisdoc/hevy-mcp (TypeScript) и SrdjanCodes/hevy-mcp (Python). Это не форк, но стоит взглянуть, если вам нужен другой язык или набор функций.

hevy-mcp — это проект сообщества, он не связан с Hevy и не поддерживается ими.