Garmin Read-Only MCP

Намеренно ограниченная интеграция с Garmin Connect для локального использования с Hermes Agent. Она синхронизирует выбранные сводки Garmin в кэш SQLite, доступный только владельцу, а затем предоставляет только этот нормализованный кэш через три инструмента MCP, доступных только для чтения.

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

Модель безопасности

Архитектура разделяет сетевой доступ и процесс MCP:

1. garmin-readonly-auth выполняет одноразовый интерактивный вход в локальном терминале. Ввод пароля и MFA скрыт и никогда не принимается в качестве аргументов команды.

2. garmin-readonly-sync загружает повторно используемые локальные данные сессии, получает данные за ограниченный диапазон дат, отфильтровывает поля из исходного API и записывает нормализованные сводки в SQLite.

3. garmin-readonly-mcp не импортирует ни клиент Garmin, ни данные сессии. Он читает только нормализованный кэш SQLite и отклоняет кэши, которые являются символическими ссылками, нерегулярными файлами, не принадлежат текущему пользователю или доступны группе/другим пользователям.

Каталог состояния по умолчанию:

~/.local/share/garmin-readonly-mcp/
├── tokens/          # Garmin session material, mode 0700/0600
└── cache.sqlite3    # normalized cache, mode 0600

Установите несекретную переменную окружения GARMIN_READONLY_HOME, чтобы использовать другой корневой каталог. Никогда не размещайте каталог состояния внутри репозитория.

Related MCP server: garmin-mcp-local

Область данных

Кэш и MCP предоставляют только:

• Общие, активные и базальные/калории покоя за день

• Шаги и пульс в покое, когда доступны

• Тип активности, время начала, продолжительность, дистанция и калории

• Продолжительность/оценка сна, Body Battery, ночной HRV/статус и готовность к тренировкам, когда доступны

Они намеренно исключают:

• Профиль Garmin и социальные данные

• Идентификаторы учетной записи и идентификаторы активностей

• Информацию об устройствах

• GPS-координаты, маршруты и файлы FIT/GPX/TCX

• Вес и композицию тела

• Необработанные ответы Garmin

• Операции загрузки, обновления, планирования или удаления

• Общий или произвольный доступ к API Garmin

Значения калорий Garmin — это контекст активности, а не команда к увеличению потребления пищи.

Требования

• Linux или другое Unix-подобное окружение с приватными правами доступа к файлам

• Python 3.12+

• uv

• Учетная запись Garmin Connect

Установка

git clone https://github.com/alexpomsft/garmin-readonly-mcp.git
cd garmin-readonly-mcp
uv sync --frozen

Аутентификация локально

Запустите это в приватном локальном терминале — не в Telegram, чате, истории команд или на общем экране:

uv run garmin-readonly-auth

Команда запрашивает локально email, скрытый пароль и скрытый MFA, если Garmin этого требует. Она сохраняет повторно используемые данные сессии, но не пароль.

Синхронизация

По умолчанию синхронизируются сегодня и вчера:

uv run garmin-readonly-sync

Можно запросить ограниченный исторический диапазон:

uv run garmin-readonly-sync --end-date 2026-08-18 --days 14

--days должен быть от 1 до 31. Ошибки провайдера заменяются фиксированным публичным сообщением, чтобы необработанные ответы Garmin и данные аутентификации не выводились.

Запуск MCP-сервера

После хотя бы одной успешной синхронизации:

uv run garmin-readonly-mcp

Сервер stdio предоставляет ровно:

• get_daily_activity(date: YYYY-MM-DD)

• get_recent_activities(days: 1..31 = 7)

• get_recovery_summary(date: YYYY-MM-DD)

Схемы инструментов отклоняют необъявленные аргументы.

Подключение к Hermes Agent

Используйте команду MCP Hermes, а не редактируйте config.yaml вручную:

hermes mcp add garmin-readonly \
  --command /absolute/path/to/garmin-readonly-mcp/.venv/bin/garmin-readonly-mcp
hermes mcp test garmin-readonly

Перезапустите Hermes после добавления сервера, чтобы его инструменты были обнаружены. Никакие учетные данные или пути к токенам сессии не передаются в конфигурацию MCP; она использует приватный корневой каталог состояния по умолчанию. Если GARMIN_READONLY_HOME был изменен, передайте только этот несекретный параметр с помощью hermes mcp add ... --env GARMIN_READONLY_HOME=/private/path.

Разработка и проверка

uv sync --frozen
uv run pytest --cov=garmin_readonly_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src tests
uv run pip-audit

Реализация разрабатывалась с использованием подхода «сначала падающие тесты». CI запускает те же самые проверки: тесты, линтинг, проверку типов и аудит зависимостей.

Ограничения

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

• Garmin может ограничивать скорость, запрашивать подтверждение или блокировать автоматизированных клиентов.

• Некоторые поля восстановления недоступны на некоторых устройствах или датах и возвращают null.

• Локальный кэш — это снимок; запускайте garmin-readonly-sync отдельно, если нужны более свежие данные.

• Этот проект не изменяет автоматически целевые показатели калорий и не предоставляет медицинских консультаций.

См. SECURITY.md для информации об обработке учетных данных и сообщении об уязвимостях.