polar-mcp (Python)

MCP-сервер: данные Polar Flow → Claude. Переписан с Node.js на Python.

Что изменилось по сравнению с JS-версией

Главное: ушли транзакции. Прошлая версия использовала exercise-transactions — это deprecated часть Polar API, где каждая тренировка отдаётся ровно один раз, а потом исчезает.

Актуальный API — обычный GET /v3/exercises?samples=true&zones=true:

• окно 30 дней, перечитывать можно сколько угодно раз
• зоны и семплы приходят сразу, отдельные запросы не нужны
• никакого хранилища/БД не требуется

Ограничение осталось одно: отдаются только тренировки, загруженные в Flow после регистрации приложения. Старые из Polar Flow недоступны.

Инструменты

Инструмент	Что отдаёт
get_exercises	Тренировки за 30 дней: пульс, зоны, cardio/muscle load, Running Index, сводка по каденсу, высоте, мощности
get_exercise	Одна тренировка по id
get_exercise_samples	Сырые секундные семплы (пульс, темп, каденс, высота, мощность)
get_sleep	Сон: стадии, sleep score
get_nightly_recharge	HRV, ANS charge, восстановление
get_cardio_load	Нагрузка, strain, tolerance (без даты — 28 дней)
get_continuous_hr	Пульс в течение дня, интервал 5 мин
get_daily_activity	Шаги, калории, активные минуты
get_physical_info	Вес, рост, HRmax, пороги, VO2max из настроек Polar

Семплы не вываливаются целиком: get_exercises отдаёт сводку (min/avg/max, набор и сброс высоты), сырые точки — только по явному запросу через get_exercise_samples.

Установка с нуля

1. Polar client

На https://admin.polaraccesslink.com создай клиента. Redirect URI: http://localhost:8080/callback Сохрани Client ID и Client Secret.

2. Токен (локально, один раз)

pip install -r requirements.txt
POLAR_CLIENT_ID=... POLAR_CLIENT_SECRET=... python setup_polar_auth.py

Windows PowerShell:

$env:POLAR_CLIENT_ID="..."; $env:POLAR_CLIENT_SECRET="..."; python setup_polar_auth.py

Скрипт выведет POLAR_ACCESS_TOKEN — сохрани.

3. Деплой на Railway

Залей в GitHub, подключи репозиторий в Railway (увидит Dockerfile сам).

Переменные в Railway → Variables:

Переменная	Значение
POLAR_ACCESS_TOKEN	из шага 2
SHARED_SECRET	любая длинная случайная строка (openssl rand -hex 32)

POLAR_USER_ID больше не нужен — актуальный API работает без него.

Settings → Networking → Generate Domain.

Проверка: curl https://твой-домен.up.railway.app/health → {"status":"ok"}

4. Подключение к Claude

Настройки → Connectors → Add custom connector

Server URL: https://твой-домен.up.railway.app/mcp/твой_SHARED_SECRET

Advanced settings оставить пустыми.

Переход с JS-версии

Если JS-версия уже развёрнута и подключена:

1. Замени в репозитории server.js/package.json/Dockerfile на файлы отсюда
2. Удали POLAR_USER_ID из Railway (не мешает, но не используется)
3. SHARED_SECRET и POLAR_ACCESS_TOKEN оставь как есть
4. URL коннектора не меняется — переподключать в Claude не нужно
5. После деплоя список инструментов обновится; если Claude показывает старый — отключи и подключи коннектор заново

Про типы семплов

Polar нумерует типы семплов, но в документации таблица неполная. В server.py есть словарь SAMPLE_TYPE_NAMES с предварительным мэппингом. В выдаче всегда присутствует sample_type_raw, так что при расхождении (например, unknown_type_8 вместо каденса) достаточно поправить словарь.