Персональный Garmin MCP

Локальный MCP-сервер для создания и планирования структурированных тренировок в Garmin Connect через неофициальные конечные точки Garmin.

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

Возможности

• проверяет сохранённую сессию Garmin;

• предпросматривает JSON Garmin без внесения изменений;

• создаёт тренировки и при необходимости добавляет их в календарь;

• выводит список библиотеки тренировок и календаря;

• читает завершённые активности, компактные сводки и метрики кругов/отрезков;

• читает доступные данные о сне, HRV, Body Battery, Training Readiness и Training Status;

• удаляет тренировки и убирает тренировки из календаря;

• поддерживает бег, велосипед, ходьбу и пешие прогулки;

• поддерживает шаги по времени, расстоянию и lap button;

• поддерживает повторение интервалов;

• поддерживает целевые показатели темпа, пульса, мощности и каденса;

• требует confirm=true для каждого изменения.

Related MCP server: garmin-mcp

Установка

Docker Compose — рекомендуется

Для локального использования требуется Docker с поддержкой Compose. Соберите образ из корня репозитория:

docker compose build

При сборке зависимости Python устанавливаются с помощью uv строго из uv.lock.

Выполните интерактивный вход один раз. Пароль и код MFA вводятся непосредственно в контейнере и не сохраняются. Токены OAuth сохраняются в приватном именованном томе garmin-mcp_garmin_tokens:

docker compose --profile login run --rm garmin-login

Запустите MCP-сервер:

docker compose up -d garmin-mcp
docker compose ps

Конечная точка доступна по адресу http://127.0.0.1:8000/mcp. Чтобы использовать другой локальный порт:

GARMIN_MCP_PORT=8765 docker compose up -d garmin-mcp

Просмотр журналов или остановка сервера:

docker compose logs -f garmin-mcp
docker compose down

docker compose down сохраняет токены Garmin. Выполнение docker compose down -v удаляет том и его токены.

Локальная установка без Docker

Требуются Python 3.12+ и uv.

cd /path/to/garmin-mcp
uv sync --extra dev

Одноразовый вход

uv run garmin-mcp-login

Скрипт в интерактивном режиме запрашивает адрес электронной почты, пароль и код MFA при необходимости. Пароль не сохраняется. Токены OAuth сохраняются в .garmin-tokens/garmin_tokens.json с ограниченными правами доступа. Каталог уже включён в .gitignore.

Чтобы сохранить токены в другом месте:

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp-login

Локальный MCP через stdio

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

Пример конфигурации MCP-клиента:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/garmin-mcp",
      "env": {
        "GARMIN_TOKEN_DIR": "/safe/private/path/garmin-tokens"
      }
    }
  }
}

Потоковый HTTP для ChatGPT

export GARMIN_MCP_TRANSPORT=streamable-http
export GARMIN_MCP_HOST=127.0.0.1
export GARMIN_MCP_PORT=8000
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

Конечная точка: http://127.0.0.1:8000/mcp.

ChatGPT должен иметь возможность доступа к конечной точке по HTTPS. Для личного тестирования можно использовать защищённый туннель. Не открывайте этот MVP напрямую в интернет: он намеренно не включает отдельный сервер ресурсов OAuth для доступа к самому MCP-серверу.

Пример аргумента preview_workout

{
  "workout": {
    "name": "6 x 800",
    "sport": "running",
    "description": "Controlled intervals",
    "blocks": [
      {
        "steps": [
          {
            "step_type": "warmup",
            "duration_type": "time",
            "duration_value": 900
          }
        ]
      },
      {
        "repeat": 6,
        "steps": [
          {
            "step_type": "interval",
            "duration_type": "distance",
            "duration_value": 800,
            "target_type": "pace_seconds_per_km",
            "target_low": 250,
            "target_high": 260
          },
          {
            "step_type": "recovery",
            "duration_type": "time",
            "duration_value": 120
          }
        ]
      },
      {
        "steps": [
          {
            "step_type": "cooldown",
            "duration_type": "time",
            "duration_value": 600
          }
        ]
      }
    ]
  }
}

Значения темпа указываются в секундах на километр: 250 = 4:10/км и 260 = 4:20/км. Сервер преобразует их в значения м/с, используемые Garmin Connect.

После предпросмотра вызовите create_workout с тем же объектом, датой в формате YYYY-MM-DD и confirm=true.

Контекст тренировок только для чтения

Сервер предоставляет компактные инструменты только для чтения для адаптации будущих планов к выполненной работе:

• list_activities выводит список активностей в заданном диапазоне дат (включительно) с необязательным фильтром по типу активности Garmin;

• get_activity_summary возвращает метрики планирования для одной активности;

• get_activity_splits возвращает компактные метрики кругов и интервалов;

• get_recovery_status объединяет доступные данные о сне, HRV, Body Battery, Training Readiness и Training Status за одну дату.

Ответы об активностях намеренно не содержат GPS-координаты и данные владельца. Метрики восстановления зависят от устройства Garmin, учётной записи и даты. Отсутствующий источник возвращается как недоступный и не приводит к сбою всего запроса на восстановление.

Проверки

uv run --extra dev pytest
uv run --extra dev ruff check .

Модульные тесты не связываются с Garmin и не требуют учётных данных.

Важные ограничения

• Это не официальный API тренировок Garmin.

• При частых входах могут возвращаться ответы HTTP 429; используйте сохранённые токены повторно.

• Токены предоставляют доступ к Garmin Connect и должны быть защищены как пароль.

• Если создание прошло успешно, но планирование не удалось, инструмент возвращает created_not_scheduled и workout_id; созданная тренировка остаётся в библиотеке.

• Перед регулярным использованием протестируйте одну простую тренировку в Garmin Connect и на конкретной модели часов.