health-mcp

你的个人健康数据库。输入由你的 agent 代劳。

一个本地优先（local-first）的服务器，用来存储你的营养、生物标志物和可穿戴设备数据。整个过程以 Model Context Protocol 工具的形式呈现，因此任何支持 MCP 的 agent（Hermes、OpenClaw）都可以读写它。当你只是想查看数据而不是与数据对话时，同一个进程里还附带了一个 Web 仪表盘。

一切都运行在你自己的机器上。一个 SQLite 文件。没有账号、没有 SaaS、没有遥测。

与其再造一个拍照数卡路里的 app 或自由文本解析器，不如让 agent 处理那些模糊的部分（"我吃了两个鸡蛋和吐司"、"把这个化验单 PDF 记下来"、"是什么影响了我的睡眠评分？"），而让这个服务器处理那些持久可靠的部分：带类型检查的 schema、原子性事务、范围查询、能力门控的工具集，以及一个不会骗你、如实展示底层数据的 UI。

它能追踪什么

营养。 食物（USDA、Open Food Facts、手动添加）、由食物 / 食谱份量 / 批次 / 自定义组件组成的餐食、饮水、体重、身体围度、以 {min, max} 表示的宏量目标，以及日 / 周汇总。

食谱和整批烹饪（Batches）。 食谱可缩放到每份对应的宏量。一份 batch 是从食谱烹饪出的一批成品，在你按份取用时逐渐消耗，log_meal 内做原子扣减，删除 batch 时自动退还。

记住的餐食。 把你常吃的早餐命名保存一次，之后一个工具调用就能重新记录。既可以保存预先解析好的组件（确定性），也可以保存规范的原始文本（每次调用由 agent 重新估算）。

生物标志物和化验。 约 30 个精选生物标志物，初始内置 LOINC 代码、默认单位和参考范围 + 最佳范围。化验病案（panel）连同全部结果一起原子地插入。三层范围判定稳妥地决定每个结果的状态：每个结果自带的化验快照 → 每个标志物的默认值 → 精选最佳范围。常见的双单位转换对（mg/dL ↔ mmol/L、ng/mL ↔ nmol/L 等）也都支持。还能做趋势查询和"最新一次"每个标志物的值。

可穿戴设备。 现支持 Whoop 和 Oura，走 OAuth2。每个厂商的镜像表都保留原始载荷（每行一个 raw_json），将来迁移时可以把任何字段提升为规范化列而不必重新同步。规范化表（wearable_sleep、wearable_activity、wearable_readiness、wearable_daily）让你跨厂商读取而不必关心连接的是谁。

洞察。 correlate 对任意两条指标序列计算 Pearson 或 Spearman，按日 / 周 / 月分桶。带符号的滞后桶可以把某条序列在时间上平移。前向填充会把上一个值带到空缺区间，因此稀疏的化验数据也能与每日可穿戴评分干净地做相关分析。在数据量达到足够有意义之前，该工具都会在 agent 的工具目录中保持隐藏。

快速开始

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 跟随最新提交。所有镜像在构建时会生成 provenance 凭证。参见 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

如果需要对 dashboard、共享类型和 server 做热重载开发，请让三者都以 watch 模式运行：

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 agent

Hermes / OpenClaw（stdio）

两者都使用标准的 MCP 配置，因此配置方式完全一致：把 health-mcp 加到 MCP agent 的 mcpServers 配置块中。无需克隆或构建，直接指向已发布的包即可：

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

配置块放在哪取决于 agent，请在它的 MCP 设置里查看路径。

然后直接告诉你的 agent：

• "把早餐的鸡蛋和吐司记下来" → log_meal

• "空腹血糖的趋势怎么样了？" → biomarker_trend

• "我的蛋白质摄入和 Whoop 第二天的恢复度相关吗？" → correlate 加上 lag_buckets: 1

想从本地 checkout 跑起来？在 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 Inspector

cd apps/server
pnpm inspect

针对一个 stdio 创建的临时进程打开 MCP Inspector，方便手工操作测试各个工具。

HTTP / 自定义客户端

Streamable-HTTP 传输被挂载在与 dashboard 同一端口的 POST /mcp 上。把任何支持 HTTP 的 MCP 客户端指向 http://127.0.0.1:7777/mcp；如果设置了 token，则发送 Authorization: Bearer <HEALTH_MCP_TOKEN> 头。

首次将一个可穿戴设备连接到 provider 需要 HTTP 服务器处于运行状态，以便回调路由能收到重定向。连接完成后，refresh token 会持久保留在 auth.json 中，stdio 模式可以一直从那里同步。

仪表盘

与数据服务器放在同一个进程，服务在 /。当前包含以下视图：

• Today —— 当日用餐、对照目标的总量/剩余、饮水、体重

• Log —— 记录进食、饮水、体重、身体围度

• Foods、Recipes、Batches —— 食物图

• Goals —— 宏量上下限、体重目标

• Labs —— 检查面板、结果、趋势、每个标志物的 About 卡

• Trends —— 周汇总

• Wearables —— provider 状态、睡眠 / 活动 / 恢复 / 每日读值

• Insights —— correlate 界面

• Settings —— token、时区、主题

基于 TanStack Router + Query、Kumo UI（基于 Tailwind v4）和 Recharts 构建。深色模式默认跟随操作系统设定；你也可以在设置里固定深/浅色。

配置

优先级：CLI 参数 > 环境变量 > JSON 配置文件 > 默认值。

每个 flag、每个环境变量、JSON 配置文件的结构，以及启动时强制保证的 privacy 不变量，都在 docs/CONFIGURATION.md。

隐私与安全

这个服务器依容并强制安全默认值。

• 只有回环（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 可以导出数据库而不携带 provider 的 token。

• 类似 Whoop 的 provider 每次使用都会轮换 refresh token。认证存储按 provider 串行化 refresh，两个并发的 401 不可能同时花掉同一个 token 导致你被锁出。

• OAuth 回调使用 HMAC 签名的 state 负荷，带 10 分钟有效期，并且在 SQLite 中保存一次性 nonce。不会重放，不会伪造。

这些安全设计能防什么、不能防什么，以及如何把服务安全暴露在 localhost 之外（TLS 终结隧道；检查 doctor 输出），详见 docs/SECURITY.md。

由什么组成

单 Node 进程。一个 Hono 应用把 MCP Streamable-HTTP 挂到 /mcp，REST 镜像挂到 /api/*，可穿戴设备 OAuth 回调挂到 /auth/wearable/callback，仪表盘 SPA 挂在 /。存储层使用 better-sqlite3，启用 journal_mode=WAL 和 foreign_keys=ON。所有业务逻辑都在 apps/server/src/services/*.ts；MCP 工具处理器和 REST 路由都是薄薄的 Zod 校验壳，真正逻辑全部委托给 service。可穿戴设备数据经过一个 WearableProvider 接口写入：每次同步调用时，原始数据按厂商镜像，规范化表按跨厂商，一次事务完成。

在 HTTP 模式下，一个 cron 任务（默认 */30 * * * *，可配置）定时为每个已链接的 provider 调用 syncWearables()。stdio 模式不启动调度器，agent 按需调用 sync_wearables 即可。

服务拆分的细节、传输层的管道以及能力门控机制，都记录在 docs/ARCHITECTURE.md。

工具面

约 60 个工具。你的 agent 可以先调用 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

能力门控会把当前不可用的工具隐藏起来，因此工具表始终精简（context 小）。可穿戴设备提供商尚未关联时，可恢复正常; 在没有值得做相关的数据之前，关联分析工具也会保持隐藏在目录中。完整的工具列表、参数、返回值与门控规则，都写在 docs/MCP.md。

文档

参与贡献

欢迎提交 Issue 和 PR。

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>/，添加包含原始镜像表的迁移，在可穿戴注册表中注册。标准化读取工具会自动识别它。具体操作见 docs/WEARABLES.md。

发布一次版本就是一次 GitHub Actions 运行完事 -- 更新版本号、打标签、发布 npm、打 GHCR 标签一次到位。参见 docs/RELEASING.md。

状态

个人项目，正在积极开发。数据模型对营养、生物标志物以及 Whoop / Oura 同步已经稳定；迁移只前进且启动时运行。在出现 1.0 标签之前，工具参数和 dashboard 路由可能产生破坏性变更。如果有任何问题卡住你，请直接提交 Issue。

这是一个个人使用工具，不是医疗建议，也不是医疗设备。它展示的价值、范围和相关性仅用于量化自身，而非诊断。

技术栈

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

Dashboard: Vite · React 18 · TanStack Router + Query · Tailwind v4 · Kumo UI · Recharts.

许可证

MIT