garmin-mcp

Небольшой MCP-сервер, который предоставляет Claude Desktop доступ только для чтения к данным Garmin Connect: пробежкам, силовым тренировкам и калориям. Включает три инструмента, настройка занимает около пятнадцати минут.

Я создал его, потому что хотел отслеживать прогресс, среди прочего, и анализировать некоторые данные своих тренировок (например, как изменился мой темп лёгкого бега или что я поднимал в дни, когда также бегал) без ручного экспорта CSV. Он напрямую общается с API Garmin Connect, поэтому никаких сторонних сервисов посередине нет, и ничего никуда не загружается.

Инструменты

• list_runs(limit, start): дата, тип пробежки, дистанция, время, средний темп, средний и максимальный пульс, каденс, температура. Также охватывает беговые дорожки.

• list_strength(limit, start): дата, название сессии, продолжительность, подходы, повторения, общие и активные калории, средний и максимальный пульс.

• daily_calories(days, end): общее количество калорий за день, активные и BMR-калории, а также шаги и пульс в покое.

start — это смещение строки, а end — дата, поэтому Claude может листать годы истории, а не только последние несколько записей.

Всё доступно только для чтения. Базовая библиотека (garth-ng) предоставляет конечные точки для записи, но здесь они не вызываются: это единственное, что делает это безопасным, поскольку сами токены предоставляют полный доступ к учётной записи.

Требования

Python 3.12+, uv, Claude Desktop и учётная запись Garmin Connect. Команды ниже предполагают оболочку Unix, то есть macOS или Linux; Windows тоже работает, но пути отличаются. Claude Desktop работает на macOS, Windows и Linux (бета-версия на Ubuntu и Debian). Это не будет работать в мобильном приложении Claude или на claude.ai, потому что локальный stdio-сервер не имеет URL для подключения.

Настройка

1. Измените пароль Garmin на тот, который вы больше нигде не используете, так как вам предстоит ввести его в скрипт.

2. Клонируйте и установите:

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. Выполните аутентификацию один раз. Это обменяет ваш пароль на токены OAuth, сохранённые в ~/.garth, после чего пароль больше никогда не понадобится:

cd garmin-mcp-public
uv run auth_setup.py

Введите код MFA, если потребуется. Токен OAuth1 действует около года, а OAuth2 обновляется автоматически, так что это примерно ежегодная рутина. Относитесь к ~/.garth как к учётным данным: любой, кто им завладеет, сможет прочитать всю вашу учётную запись Garmin.

4. Протестируйте инструменты напрямую, до подключения Claude. Ошибка на этом этапе — это проблема аутентификации или конечной точки, а не MCP, и отлаживать её на этом уровне гораздо быстрее, чем через логи Desktop:

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. Найдите два абсолютных пути, необходимых для конфигурации:

cd garmin-mcp-public
which uv
pwd

6. Создайте или отредактируйте файл конфигурации Claude Desktop и вставьте блок ниже, заменив два пути на вывод из шага 5. Вставка ваших реальных путей также удалит оба экземпляра YOUR_USERNAME. Файл находится по адресу ~/Library/Application Support/Claude/claude_desktop_config.json на macOS и %APPDATA%\Claude\claude_desktop_config.json на Windows; в бета-версии Linux проверьте документацию Anthropic по Claude Desktop для текущего расположения.

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

Оба пути должны быть абсолютными. Desktop запускает сервер с минимальным PATH, поэтому просто uv не сработает, даже если он работает в вашей оболочке. Если у вас уже настроены другие серверы, добавьте запись garmin рядом с ними, а не заменяйте объект. Если вы редактируете этот файл в TextEdit, сначала отключите умные кавычки: фигурные кавычки — это недопустимый JSON.

7. Полностью закройте Claude Desktop (Cmd-Q, а не просто закройте окно) и откройте снова. Конфигурация читается только при запуске. Затем спросите что-то вроде «покажи мои последние пять пробежек и расход калорий за эту неделю» и подтвердите вызовы инструментов.

Если не работает

Сначала проверьте JSON, затем прочитайте stderr сервера. Это пути для macOS; адаптируйте под свою платформу:

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

Ошибки при каждом вызове обычно означают, что срок действия токенов истёк: запустите auth_setup.py заново. Диалог «добавить пользовательский коннектор» внутри Claude здесь не актуален, так как он ожидает удалённый HTTPS-URL.

Примечания для тех, кто расширяет это

API Garmin Connect не документирован, и его имена полей меняются, поэтому, когда что-то возвращается пустым, лучше проверить один реальный объект, а не гадать. Сохраните это как probe.py в репозитории и запустите с помощью uv run probe.py, а не вставляйте в оболочку:

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

Два поведения, о которых стоит знать перед добавлением инструмента. Фильтр activityType принимает только родительские категории: running работает и незаметно включает treadmill_running, а strength_training возвращает HTTP 400, и его нужно запрашивать как fitness_equipment, а затем фильтровать в Python. И каждое занятие содержит около сотни полей, поэтому отображайте их на те несколько, которые вам нужны: возврат сырого JSON Garmin забивает окно контекста при каждом вызове.

По той же причине держите количество инструментов небольшим. Три целенаправленных инструмента с описательными строками документации работают лучше, чем дюжина расплывчатых, потому что именно строки документации Claude читает при выборе, какой инструмент вызвать.

Лицензия MIT.