MCP-сервер Garmin Connect

MCP-сервер для силовых тренировок в Garmin Connect. Спланируйте тренировку в диалоге с ИИ-ассистентом, отправьте её на часы и прочитайте, что вы реально подняли.

Неофициальный. Не связан с Garmin, не одобрен и не поддерживается Garmin. Garmin и Garmin Connect являются товарными знаками Garmin Ltd. Этот проект обращается к частным конечным точкам сервиса тренировок Garmin через реверс-инжиниринг клиента python-garminconnect, поэтому Garmin может изменить или сломать его без предупреждения. Используйте на свой страх и риск и проверьте свои обязательства по условиям использования Garmin.

Всё работает локально. Ваши учётные данные остаются на вашем компьютере и передаются только в Garmin.

Зачем это нужно

Garmin Connect не импортирует файлы тренировок .FIT — импорт FIT работает только для завершённых активностей, а не для запланированных тренировок. Ваши варианты — веб-интерфейс Connect вручную или та же частная конечная точка, которую вызывает само веб-приложение. Этот проект идёт вторым путём и предоставляет MCP-интерфейс, так что тренировка может появиться из разговора, а не из двадцати минут кликанья.

Инструменты

delete_workout — единственный разрушительный инструмент.

Установка

Требуется Python 3.12 или новее (garminconnect 0.3.x требует этого).

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh создаёт .venv/ в каталоге проекта, устанавливает зависимости и копирует .env.example в .env. Ничего не устанавливается в систему. Если в вашей последней версии Python ещё нет колёс для какой-либо зависимости, переопределите её:

PYTHON=python3.13 ./setup.sh

Заполните .env своими данными для входа в Garmin, затем выполните аутентификацию один раз:

./.venv/bin/python garmin_login.py

Этот шаг намеренно интерактивный. Garmin может запросить код MFA, а у MCP-сервера нет терминала, чтобы спросить — он просто зависнет. Вход кэширует токены в ~/.garminconnect, и сервер затем молча использует их. Повторно запускайте его только в том случае, если сервер сообщит об истечении сессии.

Проверьте сборку без обращения к сети:

./.venv/bin/python garmin_mcp.py --self-test

Подключение к клиенту

Claude Desktop

Добавьте в claude_desktop_config.json — на macOS в ~/Library/Application Support/Claude/, на Windows в %APPDATA%\Claude\:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

Используйте абсолютные пути и интерпретатор из venv, а не просто python — приложение не наследует PATH вашей оболочки. После этого перезапустите приложение.

Всё остальное

Это стандартный MCP-сервер stdio, поэтому подойдёт любой клиент. Для отладки вне клиента:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

Программы

Программа — это JSON-файл в programs/, описывающий многодневный шаблон. sync_program отправляет каждую тренировку в нём, сопоставляя по имени — существующие тренировки обновляются на месте, новые создаются. Смотрите programs/example.json с комментариями.

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

Блок — это повторяющаяся группа, которая выполняется repeat раз. Шаг — это либо упражнение (exercise + reps, опционально weight_kg и note), либо отдых (rest_seconds). Суперсет — это один блок, содержащий оба упражнения с коротким отдыхом между ними и длинным отдыхом в конце. Опустите weight_kg для работы с собственным весом. Опустите warmup для шага разминки по умолчанию или установите его в "" для отсутствия разминки.

programs/*.json игнорируется git, кроме примера, так что ваши собственные тренировки никогда не попадут в коммит.

Что может вас подвести

Garmin молча стирает нераспознанные названия упражнений. Загрузка возвращает 200, и упражнение отображается без названия на часах во время сессии. Именно поэтому существует search_exercises и почему каждое название сверяется с каталогом перед загрузкой. Отображаемые названия содержат дефисы так, как никто не печатает — «Rope Press-down», «Close-grip Chin-up» — поэтому поиск нормализует пунктуацию и понимает сокращения вроде «db», «bb», «ohp», «rdl», «skullcrusher».

Две части API расходятся в единицах веса. Сервис тренировок принимает weightValue в килограммах, несмотря на то, что weightUnit содержит "factor": 1000.0. Полезные данные активности — то, что вы подняли, — сообщаются в граммах. Оба варианта обрабатываются; не «исправляйте» ни один из них.

Проверка полного цикла не может поймать ошибку единиц. Она сравнивает то, что Garmin сохранил, с тем, что было отправлено, и Garmin добросовестно сохраняет всё, что вы отправляете. Когда отправлялись граммы, проверка проходила, и Connect отображал «75,000 кг». Проверьте свою первую загрузку в Connect.

Обновляйте, а не удаляйте и создавайте заново. Сохранение ID тренировки означает, что часы воспринимают изменение как редактирование. Повторное создание заставляет их удалить старые тренировки и загрузить новые, что приводит к устаревшим дубликатам.

429 и 401 выглядят одинаково. Garmin агрессивно ограничивает количество входов с IP. Когда первый транспорт входа ограничен, запасной вариант garminconnect сообщает вводящий в заблуждение 401. Если вы только что видели 429, это ограничение — подождите 30–60 минут и не повторяйте попытки в цикле, это продлевает блокировку. Чтобы исключить действительно неверный пароль: garmin_login.py --check-env.

Структура

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

Лицензия

MIT — см. LICENSE.

Создано на основе python-garminconnect (MIT) и MCP Python SDK (MIT).