oura-mcp

MCP-сервер для доступа к данным Oura Ring из Claude Code и claude.ai.

Спрашиваешь «как я спал на прошлой неделе» — Claude сам вызывает нужный инструмент и получает готовую сводку, а не гору JSON.

Особенности

• Один код — два транспорта. stdio для Claude Code локально, streamable-http для развёртывания на сервере. Различаются одним флагом.

• Сжатые ответы. По умолчанию возвращается сводка (посуточные значения + статистика с трендом), а не сырой ответ API. Полный JSON доступен через raw=True у любого инструмента.

• Песочница из коробки. Работает на тестовых данных Oura без всякой авторизации — можно поднять и попробовать за минуту.

• Устойчивость к сети. Обход пагинации next_token, ретраи с экспоненциальным бэкоффом, внятные сообщения вместо голых кодов ответа.

Related MCP server: whoop-ai-mcp

Быстрый старт

Нужен uv. Токен Oura на этом шаге не нужен.

git clone https://github.com/AntVsl/oura_mcp && cd oura_mcp
cp .env.example .env
uv sync

Проверка, что данные доходят (идёт в песочницу Oura, авторизация не нужна):

uv run python -m oura_mcp.smoke

Подключение к Claude Code:

claude mcp add oura -- uv --directory /полный/путь/к/oura_mcp run oura-mcp

Затем в сессии: «покажи сводку Oura за неделю». Инструмент get_status подтвердит, в каком режиме сервер работает.

Инструменты

Общие параметры: days_back либо пара start_date/end_date (YYYY-MM-DD), плюс raw для получения нетронутого ответа Oura.

Переход на реальные данные

Песочница отдаёт синтетику. Чтобы получить свои данные, нужно приложение Oura и разовая авторизация.

1. Зарегистрируй приложение на developer.ouraring.com/applications:

Проходить ревью не нужно: свежее приложение работает сразу, лимит — 10 пользователей.

2. Впиши OURA_CLIENT_ID и OURA_CLIENT_SECRET в .env.

3. Пройди авторизацию — один раз:

uv run oura-mcp auth

Команда поднимет локальный сервер на адресе из OURA_REDIRECT_URI, откроет браузер и после подтверждения сохранит токены в .oura/tokens.json (права 600). Дальше сервер обновляет их сам.

4. Переключи OURA_API_MODE=production в .env.

Вспомогательное:

uv run oura-mcp auth --status   # авторизован ли, сколько живёт токен
uv run oura-mcp auth --logout   # забыть токены

Personal Access Token больше не подойдёт: Oura прекратила их выпуск в декабре 2025, доступ только через OAuth2.

Refresh-токен одноразовый. При каждом обновлении Oura выдаёт новый и аннулирует прежний, поэтому два сервера с общим хранилищем выбьют друг друга из авторизации. Признак — 400 с сообщением про одноразовость: лечится повторным oura-mcp auth и переходом на один живой экземпляр.

Конфигурация

Всё через .env (см. .env.example). Секреты в git не попадают.

Почему OURA_TZ важен: на хосте в UTC системное «сегодня» отличается от твоего, и запрос «сон за вчера» вернёт не ту ночь.

Запуск

Один и тот же код обслуживает оба сценария — различается только транспорт.

Локально: Claude Code на этой машине

claude mcp add --scope user oura -- uv --directory /путь/к/oura_mcp run oura-mcp

--scope user делает сервер видимым из любого каталога; без него он подключится только в той папке, где выполнена команда. Проверка:

claude mcp list

Транспорт stdio, сеть не задействована, ничего наружу не открывается.

Локально по HTTP: отладка транспорта

uv run oura-mcp --transport http --port 8000

На loopback-адресе секрет не требуется. Здесь удобно воспроизводить то, что потом будет происходить на сервере.

Глобально: свой сервер, доступ отовсюду

Даёт доступ с любого устройства и из веб-интерфейса claude.ai. Нужны сервер с публичным IP и домен, A-запись которого уже ведёт на этот сервер.

Не разворачивай это на том же хосте, где живёт VPN: публичный HTTPS-домен на том же IP портит его репутацию и привлекает к нему внимание.

1. Подготовь секреты на сервере, в .env:

python3 -c "import secrets;print(secrets.token_urlsafe(32))"

Полученную строку — в OURA_MCP_TOKEN, домен — в OURA_DOMAIN, и OURA_TZ=Europe/Moscow (системное время сервера почти наверняка UTC).

2. Подними:

docker compose up -d

Caddy сам выпустит TLS-сертификат. Наружу смотрит только он; порт MCP остаётся внутри сети Docker. Проверка живости — curl https://твой-домен/healthz, она не требует токена и не отдаёт данных.

3. Подключи claude.ai: Settings → Connectors → Add custom connector, URL https://твой-домен/mcp. В разделе Request headers добавь заголовок Authorization со значением Bearer <твой OURA_MCP_TOKEN> — целиком, вместе со словом Bearer и пробелом.

Аутентификация по request headers у Claude в стадии beta и раскатана не на всех. Если раздела в диалоге нет, дождись доступа — обходной путь требует полноценного OAuth 2.1-сервера на стороне MCP.

4. Подключи Claude Code с любой машины:

claude mcp add --scope user --transport http oura https://твой-домен/mcp --header "Authorization: Bearer ТВОЙ_ТОКЕН"

Без заголовка или с неверным токеном эндпоинт отвечает 401 и до данных не допускает.

Что выбрать

Держи один живой экземпляр: refresh-токен Oura одноразовый, и два сервера с общим хранилищем токенов будут выбивать друг друга из авторизации. Подняв удалённый, переключи на него и локальный Claude Code — вариантом из шага 4.

Безопасность

• .env, хранилище токенов и кэш перечислены в .gitignore. Проверяй перед коммитом: git status --porcelain.

• Refresh-токен Oura одноразовый — при каждом обновлении выдаётся новый. Два экземпляра сервера с одним токеном будут выбивать друг друга из авторизации. Держи один живой инстанс: когда поднимешь удалённый, направляй на него и Claude Code.

• HTTP-эндпоинт закрыт общим секретом OURA_MCP_TOKEN (сравнение постоянного времени). Модель доступа намеренно простая: один секрет, один владелец, разграничения между пользователями нет.

• Сервер не запустится на внешнем адресе без секрета — вместо тихой отдачи медданных в открытый интернет он откажется стартовать. Проверить локально: uv run oura-mcp --transport http --host 0.0.0.0.

• Путь /healthz открыт без токена намеренно — он нужен reverse proxy и не отдаёт ничего, кроме ok.

• Заголовок Authorization вычищается из логов Caddy.

Разработка

uv run pytest

Тесты идут на зафиксированных ответах и сеть не трогают.

x86_64 macOS: cryptography с версии 49 не публикует бинарное колесо под эту платформу и пытается собраться из Rust-исходников. В pyproject.toml стоит прицельное ограничение на 48.0.0; Linux и нативный arm64 оно не затрагивает.

Это касается не только Intel-машин. Если Homebrew установлен в /usr/local (а не в /opt/homebrew), то на Apple Silicon весь Python-стек всё равно x86_64 и идёт через Rosetta. Проверить: file $(which python3).

Перебои сети: если запросы к api.ouraring.com рвутся с SSL_ERROR_SYSCALL или таймаутом, дело обычно не в сервере. Клиент делает 4 попытки с бэкоффом; если не помогает — включи VPN.

Лицензия

MIT