health-mcp

Ваша личная база данных о здоровье. Ввод данных делает ваш агент.

Сервер, построенный по принципу local-first, который хранит ваши данные о питании, биомаркерах и носимых устройствах. Всё это доступно как инструменты Model Context Protocol, поэтому любой MCP-совместимый агент (Hermes, OpenClaw) может их читать и записывать. В этом же процессе работает веб-дашборд — на случай, когда на данные хочется смотреть, а не разговаривать с ними.

Всё работает на вашей машине. Один файл SQLite. Никаких аккаунтов, никакого SaaS, никакой телеметрии.

Вместо того чтобы вновь приложение для подсчёта калорий из фото (photo-CV) или парсер свободного текста, вы отдаёте агенту нечёткую часть („Я съел два яйца и тост“, „занеси этот лабораторный PDF“, „что влияет на мой балл сна?“), а серверу — постоенную часть: типизированнуюю схему, атомарные транзакции, диапазонные запросы, поверхность инструментов с ограниченными возможностями, UI, который не искажает даные данные под ним.

Что он отслеживает

Питание. Продукты (USDA, Open Food Facts, вручную введённые), приёмы пищи, составленные из компонентов „продукт / порция рецепта / партия / своё“, гидратация, вес, замеры тела, цели по макронутриентам в виде границ {min, max} и дневные / недельные сводки.

Рецепты и приготовленные партии. Рецепты пересчитываются на макроэлементы на порцию. Партия — это итоговый судочный вариант, который расходится по мере того, как вы из неё едите; при вызове log_meal происходит атомарное списание, а при удалении — возврат.

Запоминаемые приёмы. Вы один раз размечаете свой обычный завтрак, а затем повторно вносите его одним вызовом инструмента. Это либо заранее разрешённые компоненты (детерминированно), либо просто канонический свободный текст (агент переоценивает его при каждом вызове).

Биомаркеры и лаборатории. Около 60 курируемых биомаркеров с кодами LOINC, единицами по умолчанию и диапазонами нормы + оптимума. Отдельные анализы и панели вносятся атомарно. Трёхэтапный проход по референсным интервалам определяет статус каждого результата: референсный снимок конкретного результата → загадка по умолчанию для биомаркера → курируемый оптиум. Поддерживается пересчёт единиц для распространённых пар (mg/dL ↔ mmol/L, ng/mL ↔ nmol/L и т. д.). Доступны запросы тренда и „последнее значение по маркеру“.

Носимые устройства. Пока это Whoop и Oura через OAuth2. Для каждого провайдера сохраняется сырой ответ (поле raw_json в каждой строке), так что в будущем миграция может перенести любое поле в нормализованную колонку без повторной синхронизации. Нормализованные таблицы (wearable_sleep, wearable_activity, wearable_readiness, wearable_daily) позволяют читать данные независимо от вендора, а токены освежителя ротируются. Если два 401-ответа наступают параллельно, они не могут потратить один и тот же токен повторно, потому что хранилище авторизации защищено мьютексом для каждого провайдера.

Инсайт. correlate вычисляет корреляцию Пирсона или Спирмана между любыми двумя рядами метрик, группируя их по дням / неделе / месяцу. С баз для запаздывания одна серия сдвигается во времени. Передача последнего значения вперёд закрывает разрывы, поэтому разрежённые данные лаборатории позволят корректно сопоставить их с ежедневными показателями носимых устройств. Инструмент остаётся скрытым из каталога агента, пока данных достаточно мало.

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

npx

Node ≥ 20 без клонирования и сборки:

npx health-mcp            # http://127.0.0.1:7777, opens the dashboard
npx health-mcp --stdio    # headless MCP server over stdio

State живёт в ~/.health-mcp/ (одинный файл SQLite). npx health-mcp --help покажет все флаги, npx health-mcp doctor запустит самопроверку.

Docker

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
cp .env.example .env

# Put a strong token in .env (required to bind off-loopback)
openssl rand -hex 32

docker compose up -d
open http://127.0.0.1:7777

Данные сохраняются в именной том health-mcp-data. Если удобнее видеть файлы на диске, замените маунт в docker-compose.yml на ./.health-mcp-data:/data.

docker compose down останаваливает контейнер; данные сохраняются между перезапусками.

Предпочитаете готовый образ сборке из исходников? Укажите в docker-compose.yml опубликованный образ и удалите блок build::

image: ghcr.io/lukaisailovic/health-mcp:latest   # or pin :0.1.0 / :0.1

Каждый выпуск размещает :X.K, , :X.Y и :latest; тег :main соответствует самой свежей сборке. Образ сопровождаются атрибуцией происхождения сборки. См. раздел Релизы.

Из исходника

Node ≥ 20 и pnpm.

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
pnpm install
pnpm build
pnpm start                      # http://127.0.0.1:7777, browser opens automatically

Для разработки с горячей перезавагрузкой дашборда, общих типов и сервера запустите все три компонента в режиме watch:

pnpm dev
# server on :7777, dashboard dev on :5173 (proxies /api/* to :7777)

Передайте --no-open, чтобы не открывался браузер, или --no-dashboard, чтобы работать как headless MCP / REST-сервер.

Подкоманды

pnpm start -- migrate                  # apply pending DB migrations and exit
pnpm start -- doctor                   # self-check (DB pragmas, file modes, token entropy)
pnpm start -- export /tmp/dump.jsonl   # JSONL dump; raw_json redacted unless --include-raw
pnpm start -- import-usda dump.json    # ingest a USDA FoodData Central bulk JSON

Подключение MCP-агента

Hermes / OpenClaw (stdio)

Оба агента используют стандартную конфигурацию MCP, поэтому настройка одинакова: добавьте health-mcp в mcpServers вашего агента. Клонировать и собирать не нужно: укажите опубликованный пакет:

{
  "mcpServers": {
    "health": {
      "command": "npx",
      "args": ["-y", "health-mcp", "--stdio"]
    }
  }
}

Где именно находится этот блок, зависит агент; посмотрите путь в его MCP Settings.

Затем скажите своему агенту:

• „Запиши яйца и тост на завтрак“ → log_meal

• „Как у меня меняется голодная глюкоза?“ → biomarker_trend

• „Ивают ли мои белки на восстановление Whoop на следующий день?“ → correlate с lag_buckets: 1

Используете локальную копию? Тогда примените "command": "node" с "args": ["/path/to/health-mcp/apps/server/dist/index.js", "--stdio"] после pnpm build, либо "args": ["--import", "tsx", "/path/to/health-mcp/apps/server/src/index.ts", "--stdio"], чтобы без сборки.

MCP Inspector

cd apps/server
pnpm inspect

Запускает MCP Inspector для stdio-дочернего процесса, чтобы пощупать инструменты вручную.

HTTP / кастомный клиент

Транспорт Streamable-HTTP смонтирован на POST /mcp на том же порту, что и дашборд. Направьте любой HTTP-совместимый MCP-клиент на http://127.0.0.1:7777/mcp и укажите Authorization: Bearer <HEALTH_MCP_TOKEN> при заданном токене.

Первому OAuth-подключению к провайдеру носимых данных требует работающих HTTP-серверы, потому что маршрут обратного вызова должен получить редирект. После подключения ref-токен хранится в auth.json, и stdio-режим может синхронизироваться оттуда бессрочно.

Дашборд

Отдаётся по адресу / этим же процессом. Страницы на данный момент:

• Today — питание за выбранный день, итоги по целям, гидратация, вес

• Log — добавить приёмы пищи, окну, вес, замеры тела

• Foods, Recipes, Batches — переписка продуктов и рецептов *Foods — список продуктов

• Goals — цели по макронутриентам и целевой вес

• Labs — паспорта, результаты, потенциалы, карточка „О показателе“

• Trends — недельные сводки

• Wearables — статус провайдера, данные о сне, активности, восстановлении, дню

• Insights — интерфейс для correlate

• Settings — токен, таймог, тема

Основан на TanStack Router + Query, Kumo поверх Tailwind v4 и Recharts. Тёмная тема по умолчанию отражает системную; в Settings её можно закрепить.

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

Приоритет: флаг CLI > переменная окружения > JSON-файл конфигурации > значение по умолчанию.

Каждый флаг, переменная окружения, схема JSON-файла конфигурации и проверки безопасностей на старте описаны в docs/CONFIGURATION.md.

Приватность и безопасность

Сервер работается по принципу fail closed — при нештатной ситуации блокирует работу.

• Безопасный вариант по умолчанию — только loopback. Для привязки к другому адресу нужно установить HEALTH_MCP_TOKEN из строки с высокой энтропией длиной 32+ символов (openssl rand -hex 32); иначе сервер откажется стартовать, мягкой замены нет.

• data.db и auth.json создаются с правами 0600 внутри каталога с в 0700. Если права более широкие, сервер откажется открыть файлы, пока вы не передадите --allow-insecure-db / --allow-insecure-auth.

• OAuth-данные носимых провайдеров хранятся в ~/.health-mcp/auth.json, отдельного от data.db, поэтому health-mcp export может передать базу, не передавая токены провайдера.

• Провайдеры вроде Whoop чередуют все обновления токенов. Хранилище авторизации сериализует обновление токенов для каждого провайдера, чтобы две параллельные отвязки 401 не израсходовали один и тот же.

• Про колб источник токи в OAuth — это подписанное HMAC состояние со сроком жизни minutes и одноразовым номером в SQLite. Без повторов и подделки.

Что этот подход защищает, в остальном — см. docs/SECURITY.md; там же про TLS-туннель и doctor-вывод.

Как устроено всё

Один Node-процесс. Монூnt: Hono приложение поднимает MCP Streamable-HTTP на /mcp, REST-зеркало на /api/*, OAuth callback носимых на /auth/wearable/callback, и SPA-дашборд на /. Хранилище — SQLite через better-sqlite3 с journal_mode=WAL и foreign_keys=ON. Вся бизнес-логика лежит в apps/server/src/services/*.ts; обработчики инструментов MCP и REST-пути - это тонкие судил через Zod-обёртки, которые делегjiруют. Данные носимых идут через WearableProvider, который в одной транзакции пишет и сырые зеркала вендоров, и норма ризованные сквозные таблицы.

В HTTP-режиме cron-задача (*/30 * * * * по умолчанию, настраивается) вызывает syncWearables() для каждого подключённого провайдера. Stdio-режим пропускает планировщик; агенты могут вызывать sync_wearables по требованию. развёртка.

Разложение по сервисам, транспорт и rules of capability gating — в docs/ARCHITECTURE.md.

Инструменты

Около 60 инструментов. discover_capabilities возвращает действующую каталог, сгруппированную по области, с текущими флагами включить, чтобы агенты сразу видели, что доступно, а не гадали.

ping, discover_capabilities

# food
search_food, search_foods, lookup_barcode, get_food
create_custom_food, bulk_upsert_custom_foods, update_custom_food, delete_custom_food

# meals
log_meal, list_meals, get_meal, update_meal, delete_meal, undo_last_meal,
add_meal_component, update_meal_component, remove_meal_component

# recipes + batches
create_recipe, update_recipe, delete_recipe, list_recipes, get_recipe
create_batch, list_batches, get_batch, archive_batch, delete_batch

# remembered meals  (read tools hidden until you save one)
remember_meal, list_remembered_meals, get_remembered_meal,
update_remembered_meal, forget_meal, log_remembered_meal

# simple logs
log_hydration, list_hydration, delete_hydration
log_weight,    list_weight,    delete_weight
log_measurement, list_measurements, delete_measurement
get_goals, set_goals

# summaries
daily_summary, weekly_summary, range_summary

# biomarkers + labs
search_biomarker, get_biomarker, create_custom_biomarker, update_biomarker, set_optimal_range
log_lab_panel, log_lab_result, list_lab_results, latest_biomarkers, biomarker_trend
list_lab_panels, get_lab_panel, delete_lab_result, delete_lab_panel

# insights  (hidden until ≥7 days intake AND (≥1 wearable_daily row OR ≥3 lab_results))
correlate, list_correlate_metrics

# wearables  (most hidden until a provider is linked)
wearables_list_providers, wearables_status,
wearable_connect_url, wearable_disconnect, sync_wearables,
wearable_sleep, wearable_activity, wearable_readiness, wearable_daily, wearable_metric_minutes,
set_activity_type_map

# whoop  (hidden until linked)
whoop_recovery, whoop_cycles, whoop_sleep_raw, whoop_workouts_raw,
whoop_profile, whoop_body_measurement

Capability gating скрывает инструменты, которыми агент сейчас не может воспользоваться, поэтому поверхность остаётся компактной. Чтение носимых скри́то до подключения провайдера; correlate появляется только при достаточной заглушки. Полный каталог с параметрами, формами ответов и правилом gating — в docs/MCP.md.

Документация

Участие в проекте

Приветствуются issues и PRs.

pnpm install
pnpm typecheck && pnpm lint && pnpm test

Несколько базовых правил:

• Бизнес-логика живёт в apps/server/src/services/. MCP-инструменты (src/mcp/tools/) и REST-маршруты (src/rest/) — тонкие обёртки вокруг неё. Не кладите логику в обработчики.

• Миграции — TypeScript-модули, зафиксированные в репозитории по пути apps/server/src/db/sql/000N-*.ts. Только вперёд, без откатов.

• Общие схемы Zod живут в packages/shared — здесь сервер и дашборд сходятся на едином описании.

• Для новых сервисов нужен Vitest-тест (*.test.ts) либо покрытие через интеграционный набор (apps/server/src/integration.test.ts).

• Перед пушем прогоняйте pnpm lint:fix — это Biome.

Добавление нового провайдера носимых устройств — самодостаточная задача: создайте apps/server/src/wearables/providers/<id>/, добавьте миграцию с зеркальными таблицами для raw-данных и зарегистрируйте провайдера в реестре носимых устройств. Инструменты чтения нормализованных данных подхватят его автоматически. Пошаговое руководство — в docs/WEARABLES.md.

Релиз выпускается одним запуском GitHub Actions: поднятие версии, тег, npm publish и GHCR-теги — всё разом. См. docs/RELEASING.md.

Статус

Проект в одном лице, активно развивается. Модель данных стабильна для питания, биомаркеров и синхронизации Whoop / Oura; миграции выполняются только вперёд и запускаются при старте. До тега 1.0 ожидайте ломающие изменения в параметрах инструментов и маршрутах дашборда. Если что-то вас полностью блокирует — заводите issue.

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

Технологии

Node ≥ 20 · pnpm · TypeScript (ESM, strict) · Hono · @modelcontextprotocol/sdk v1 · better-sqlite3 · Zod · croner · Vitest · Biome.

Дашборд: Vite · React 25 · TanStack Router + Query · Tailwind v4 · Kumo UI · Recharts.

Лицензия

MIT.