health-mcp

나만의 개인 건강 데이터베이스. 에이전트가 대신 기록해드립니다.

로컬 우선(local-first) 서버로, 영양·바이오마커·웨어러블 데이터를 저장합니다. 모든 것이 Model Context Protocol 도구로 노출되므로, MCP를 지원하는 에이전트(Hermes, OpenClaw)라면 누구든 데이터를 읽고 쓸 수 있습니다. 데이터를 말로 다루는 대신 직접 보고 싶을 때는 같은 프로세스에서 웹 대시보드를 제공합니다.

모든 것은 사용자 컴퓨터에서 실행됩니다. SQLite 파일 하나뿐입니다. 계정도, SaaS도, 원격Telemetry도 없습니다.

또 하나의 사진 기반 칼로리 앱이나 자유 형식 텍스트 파서를 만드는 대신, 에이전트가 "질척한" 부분(“달걀 두 개와 투스트를 먹었어요”, “이 검사 PDF를 기록해줘”, “내 수면 점수에 영향을 주는 건 뭘까?”)을 처리하고, 이 서버는 견고한 부분—타입이 정의된 스키마, 원자적 트랜잭션, 범위 조회, 캐퍼빌리지로 게이트된 도구 표면, 그리고 밑의 데이터를 그대로 보여주는 UI—를 처리하게 하세요.

프레스 전환**: 여기서는 추가 설명을 위해 불 필요한 텍스트를 제거했습니다.

추적하는 것

영양. 식품(USDA, Open Food Facts, 수동 입력), 식품/레시피 제공량/배치/사용자 정의 성분으로 구성된 식사, 수분 보충, 체중, 신체 치수, {min, max} 범위로 평가하는 매크로 목표, 그리고 일일/주간 요약.

레시피와 조리 배치. 레시피는 1인 제공량 매크로로 확산됩니다. 배치는 실제로 조리된 단위이며, log_meal 안에서 원자적으로 감소하고 세션에서 삭제하면 함께 상환됩니다.

기억된 식사. 평소 아침 식사에 한번 라벨을 붙여 두면, 다음에는 단일 툴 호출로 다시 기록합니다. 사전에 매핑된 구성 요소(결정적) 또는 원본 자유 텍스트(호출할 때마다 에이전트가 다시 추산)를 유지합니다.

바이오마커와 검사실. 약 60개의 정선된 바이오마커에 LOINC 코드, 기본 단위, 참고 범위와 최적 범위가 표시입니다. 검사 패널은 모든 결과와 함께 원자적으로 삽입됩니다. 3단계 범위 탐색으로 각 결과의 상태를 결정합니다: 결과마다의 검사 스냅샷 → 생체마커별 기본값 → 정선된 최적값. 일반적인 이중 단위 쌍(mg/dL ↔ mmol/L, ng/mL ↔ nmol/L 등)에 대한 단위 변환. 추세와 “마커별 최신” 쿼리도 지원합니다.

웨어러블. 현재는 Whoop과 Oura를 OAuth2로 연결합니다. 각 provider 미러는 원본 payload를 보관하고(raw_json 행 당), 이후 마이그레이션에서 재동기화 없이 특정 필드를 정규화된 컨럼으로 승격된 수 있습니다. 정규화된 테이블(wearable_sleep, wearable_activity, wearable_readiness, wearable_daily)은 어디 한 벤더가 연결되어 있는지 아돌 것 없이 벤더를 뛰어넘너 섞어 읽을 수 있게 해줍니다. refresh 토큰은 회전하며, 인증 스토어가 제공자별로 mutex로 종료되므로 동시 401이 토큰을 이중으로 사용할 수 없습니다.

인사이트. correlate 는 일/주/월 버킷으로 나누어 두 대표 시리즈 기술에 대해 피어슨이나 스피어만 상관을 실행합니다. 부호 있는 태그 버킷은 한쪽 시리즈를 시간 지연시키며, forward-fill로 결측 구간을 마지막 값으로 채워 희귀한 검사 데이터가 지속적인 웨어러블 점수와 잘 상관되도록 합니다. 유의미한 데이터가 쌓일 때까지 이 툴은 에이전트 카탈로그에 숨겨져 있습니다.

빠른 시작

npx

Node ≥ 20, 복제나 빌드 필요 없음:

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

데이터는 ~/.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.Y.Z, :X.Y, :latest 태그를, :main은 가장 최근 커밋을 추적합니다. 모든 이미지에는 build-provenance 증명(attestation)이 포함됩니다. Releasing을 참조하세요.

소스에서 직접

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

대시보드, 공유 types, 서버에서 핫 리로드를 사용하는 개발을 원한다면, 세 가지 모두 감시 모드로 실행하세요:

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

--no-open 를 전달하면 브라우저가 열리지 않고, --no-dashboard을 전달하면 헤드리스 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 구성을 사용하므로 설치는 동일합니다: 에이전트의 mcpServers에 health-mcp를 추가하세요. 복제하거나 빌드할 필요 없이 배포된 패키지를 가리키면 됩니다:

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

이 블록의 위치는 에이전트별로 다르고, 해당 에이전트의 MCP 설정에서 경로를 확인하세요.

그런 다음 에이전트에게 물어보세요:

• "«아침에 계란과 토스트 기록해줘» → log_meal

• "혈당 공복 상태에 어떻게 trend? » → biomarker_trend

• "단백질 섭취량과 다음 날 Whoop 회복 점수 상관관계 있어?" → correlate with lag_buckets: 1

로컬에코드를 사용한다면? pnpm build 후 "command": "node"와 함께 "args": ["/path/to/health-mcp/apps/server/dist/index.js", "--stdio"]를 사용하거나, 빌드를 건너뛰려면 "args": ["--import", "tsx", "/path/to/health-mcp/apps/server/src/index.ts", "--stdio"]를 사용합니다.

MCP 인스펙터

cd apps/server
pnpm inspect

stdio 자식 프로세스로 MCP 인스펙터를 열어 도구를 직접 조사할 수 있습니다.

HTTP / 사용자 클라이언트

Streamable-HTTP transport는 대시보드 포트와 같은 포트의 POST /mcp에 마운트됩니다. HTTP를 인식하는 MCP 클라이언트는 http://127.0.0.1:7777/mcp를 가리키고, 토큰이 설정되어 있으면 Authorization: Bearer <HEALTH_MCP_TOKEN> 보낼 합니다.

웨어러블 제공자에 처음 OAuth link 연 트은 콜백 라우트가 리디렉트를 받을 수 있도록 HTTP 서버가 실행되어야 합니다. 연결되고 나면 리프레이쉬 토큰이 auth.json에 유지되므로 stdio 모드는 이후로 계속 동기화할 수 있습니다.

대시보드

같은 프로세스에서 /에 서빙됩니다. 현재 제공되는 페이지:

• Today — 그날의 식사, 목표 대비 합계, 수극, 시간대 체중

• 탭 로그 — 식사, 수극, 체중, 몸 치수를 추가

• Foods, Recipes, Batches — 식품 그래프

• Goals — 매크로 범위, 목표 체중

• Labs — 패널, 결과, 추세, 바이아마커별 About 카드

• Trends — weekly 요약

• 신체적 일기 — wearable status, 수면 / 활동 / 현조 / 일일 리딩

• Insights —데이터 상관 UI

• Settings — 토큰, 시간대, 테마

TanStack Router + Query, Tailwind v4 위의 Kumo UI, 그리고 Recharts로 구축된 대시보드를 포함합니다. 어두 apt 모드는 기본적으로 OS 설정을 따릅니다. Settings에서 고정할 수 있습니다.

설정

우선순위: CLI 플래그 > 환경 변수 > JSON 설정 파일 > 기본값.

entry — 모든 플래그와 환경 변수, JSON 설정 파일 스키마, 그리고 시작 시 적용되는 보안 invariant◦는 docs/CONFIGURATION.md 문서에 있습니다.

개인정보 및 보안

서버 것은 실폐 시 차단(fail closed) 기본으로 되어 있습니다.

• Loopback 만이 안전한 기본입니다. 바인딩을 다른 곳에 하려면 HEALTH_MCP_TOKEN을 32자 이상의 고엔트로피 문자열(openssl rand -hex 32) 으로 설정해야 합니다. 그렇지 않으면 소프트 대체 없이 서버 시작을 거부합니다.

• data.db 및 auth.json은 0700 권한의 부모 디렉터리 안에서 0600 권한으로 만들어집니다. 권한이 더 느으면 --allow-insecure-db / --allow-insecure-auth 를 넘기지 않는 한 열지 않습니다.

• 웨어러블 OAuth 자격 증명은 ~/.health-mcp/auth.json에 저장되어 data.db 와 분리되므로, health-mcp export가 데이터베이스를 전송하면서도 공급자 토큰을 누출하지 않습니다.

• Whoop 같은 공급자들은 매번 사용할 때마다 refresh 토큰을 회전합니다. 인증 저장소는 공급자별로 refresh를 직렬화하므로, 두 동시 401이 같은 토큰을 지출하는 일이 없고, 잠금되지 않습니다.

• OAuth 콜백은 HMAC 서명된 state payload를 사용합니다. 이 payload는 10분 만료되고 SQLite에 저장된 일회용 nonce로 비재생·위조를 막습니다.

이 기능이 방어하는 것들, 방어하지 못하는 것들, 그리고 localhost 밖에서 서버를 안전하게 노출하는 법(TLS 터미네움 터널; doctor 출력 확인)은 docs/SECURITY.md 에서 확인합니다.

구조

하나의 Node 프로세스입니다. Hono app이 MCP Streamable-HTTP transport을 /mcp에, REST mirror를 /api/*에, wearable OAuth 콜백을 /auth/wearable/callback에, 그리고 대시보드 SPA를 /에 마운트합니다. 스토리지는 better-sqlite 에 의한 SQLite로 journal_mode=WAL, foreign_keys=ON 이며, 모든 비즈니스 로직은 apps/server/src/services/*.ts에 있습니다. MCP 도구 핸들러와 REST 라우트는 Zod 검사를 거치는 얇은 wrapper이고, 위임합니다.

웨어러블 데이터는 WearableProvider 인터페이스를 통해 각 벤더 로우 미러 및 정규화된 벤더 cross 테이블이 동기화 페이지(x 행, 즉 한 번의 동기화 단위)마다 대상별 전용으로 쓰입니다.

HTTP 모드에서는 크론 작업(*/30 * * * *기본값, 설정 가능한)이 연결된 모든 공급자의 syncWearables()를 호출합니다. Stdio 모드는 스케줄러를 사용하지 못하고, 에이전트가 필요 시 sync_wearables를 호출합니다.

각 서비스에 대한 상세, 전송 파이프라인, 그리고 캡짐블리티 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은 에이전트가 현재 사용할 수 없는 도구를 숨어 있게 유지하여, surface 영역을 작게 안정시킵니다. wearable read는 특정 provider가 링크될 때까지 보이지 않고, correlate는 상관 측정을 할 만큼 데이터 최소 있어야 보입니다. 파라미터, 반환 구조, 게이팅 규칙이 들어간 전체 카탈로그는 docs/MCP.md에 있습니다.

파일폐이트

기여

이슈와 PR은 언제나 환영합니다.

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

몇 가지 기본 원칙:

• 비즈니스 로직은 apps/server/src/services/에 둡니다. MCP 도구(src/mcp/tools/)와 REST 라우트(src/rest/)는 그 로직을 감싸는 얇은 래퍼입니다. 핸들러에 로직을 넣지 마세요.

• 마이그레이션은 apps/server/src/db/sql/000N-*.ts에 체크인되는 TypeScript 모듈입니다. 순방향(forward-only)입니다.

• 공유 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 게시, GHCR 태그가 한 번에 처리됩니다. docs/RELEASING.md를 참고하세요.

상태

솔로 프로젝트로, 활발하게 개발 중입니다. 영양, 바이오마커, 그리고 Whoop / Oura 동기화에 대해서는 데이터 모델이 안정적입니다. 마이그레이션은 순방형(forward-only)이며 부팅 시 실행됩니다. 1.0 태그가 찍히기 전까지는 도구 파라미터와 대시보드 라우트에 큰 변경이 있을 수 있습니다. 막히는 문제가 있으면 이슈를 등록해 주세요.

이것은 개인 사용 목적의 도구이므로 의학적 조언이나 의료 기기가 아닙니다. 제공하는 수치, 범위, 연관성은 자기 측정(self-quantification)을 위한 것이고 진단을 위한 것이 아닙니다.

기술

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

대시보드: Vite · React 18 · TanStack Router + Query · Tailwind v4 · Kumo UI · Recharts.

라이선스

MIT.