garmin-mcp

Локальный MCP-сервер, который предоставляет данные вашей активности, здоровья и тренировок из Garmin Connect (активности, HRV, сон, частота сердечных сокращений, стресс, Body Battery, готовность к тренировке, зоны ЧСС/мощности, лактатный порог, FTP, VO2max, личные рекорды, тренировки, запланированные тренировки и тренировочные планы) в виде инструментов внутри Claude Desktop.

Он напрямую работает с действующим API Garmin Connect через библиотеку garminconnect. Данные доступны только для чтения — ничего не записывается обратно в Garmin.

Как работает авторизация

Вход в Garmin намеренно происходит в двух отдельных местах:

• scripts/setup_auth.py — интерактивный скрипт, который вы запускаете сами в терминале. Он выполняет вход с вашим email/паролем, запрашивает MFA-код, если Garmin его требует, и сохраняет полученный токен сессии в ~/.garmin_mcp/tokens.

• MCP-сервер (src/garmin_mcp/server.py), запускаемый Claude Desktop в фоновом режиме, только загружает и незаметно обновляет этот кэшированный токен. Он никогда не запрашивает MFA — Claude Desktop не предоставляет ему терминал для запроса, и блокировка на stdin там приведёт к зависанию вызовов инструментов. Если кэшированная сессия отсутствует или истекла, вызовы инструментов завершаются ошибкой с указанием повторно запустить setup_auth.py.

Ваш пароль Garmin хранится в связке ключей macOS (элемент/служба garmin-mcp, просматривается в Keychain Access), и никогда не записывается в файл. Сохраняется только ваш email для входа в Garmin (не секретный) — в ~/.garmin_mcp/config.json.

Установка

1. Установите зависимости:

   cd garmin_mcp
   uv sync

2. Выполните однократный интерактивный вход:

   uv run python scripts/setup_auth.py

   Введите email и пароль от Garmin Connect (пароль будет сохранён в связке ключей для следующего раза). Введите MFA-код по запросу. В случае успеха вы увидите подтверждение и путь к кэшу токенов.

3. Зарегистрируйте сервер в Claude Desktop, отредактировав ~/Library/Application Support/Claude/claude_desktop_config.json и добавив (рядом с другими записями mcpServers):

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. Полностью завершите работу Claude Desktop (Cmd+Q, а не просто закройте окно) и откройте его снова. На иконке инструментов (молоток) должны появиться инструменты garmin.

Инструменты

Все параметры даты принимают формат YYYY-MM-DD и по умолчанию равны сегодняшней дате.

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

Если вызов инструмента возвращает сообщение «Garmin session error» / «run setup_auth.py». Ваш кэшированный токен обновления истёк или был отозван (это иногда случается, например, после смены пароля или длительного отсутствия активности). Повторно запустите:

uv run python scripts/setup_auth.py

Ограничение частоты запросов. Garmin Connect иногда ограничивает частоту быстрых запросов; используемая библиотека автоматически повторяет временные сбои, но если вы видите ошибку ограничения частоты, подождите немного и попробуйте снова.

Проверка сервера напрямую, вне Claude Desktop:

uv run mcp dev src/garmin_mcp/server.py

открывает MCP Inspector, чтобы вы могли вызывать каждый инструмент вручную и проверять его вывод/схему.

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

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login