Nutrition MCP

Nutrition MCP

一款用于个人营养追踪的远程 MCP 服务——通过对话记录餐食的热量、宏量营养素、膳食纤维、总糖和添加糖、饱和脂肪和反式脂肪、钠（可选设置每日上限）以及咖啡因（可按配料分别记录）；在 USDA FoodData Central 查询通用食品，并通过 Open Food Facts 的条形码查询包装食品；记录每项营养素数据的来源；保存常吃的餐食并按名称再次记录；记录饮水量、体重和身体测量数据；查看营养历史；还可从其他应用导入已有的饮食日记。酒精追踪为可选功能，默认关闭。网站和聊天内小组件提供英语、德语、西班牙语、法语、荷兰语、波兰语、意大利语、乌克兰语、日语和土耳其语；set_language 用于设置小组件语言。

在 Patreon 上支持服务器费用

目录

• 快速开始
• 演示
• 技术栈
• MCP 工具
• MCP 资源
• 自托管
  • 0. 获取代码
  • 1. 配置 Supabase
  • 2. 环境变量
  • 3. Google 登录（可选）
• 开发
  • 测试与质量
• 连接到 Claude.ai
• Apple Health 同步
• 故障排除
• API 端点
• 部署
• 支持与安全
• 数据来源
• 许可证

快速开始

服务已托管并可直接使用——只需将其连接到你的 MCP 客户端：

https://nutrition-mcp.com/mcp

在 Claude.ai 上： 打开 Claude 目录中的 Nutrition MCP，然后点击 Connect（请参阅下文的连接到 Claude.ai）

首次连接时，请使用 Google 登录，或输入电子邮件和密码，然后选择 Create account。重新连接后，你的数据仍会保留。连接遇到问题？请参阅故障排除。

连接即表示你同意服务条款；数据处理方式请参阅隐私政策。

要从其他追踪应用切换过来？请参阅营养应用替代方案——了解它与 MyFitnessPal、Cronometer、Lose It!、MacroFactor、Yazio 和 Lifesum 的比较。带上你的历史数据：发送“导入我的餐食”，聊天中便会打开导入器，你可以选择从旧应用导出的 CSV，映射列，并在保存任何内容前检查将要添加的数据。导入器会自动识别 MyFitnessPal、Cronometer、Lose It! 和 MacroFactor 导出的文件；其他 CSV 文件也可以使用，只需自行映射其列。对于无法显示聊天内面板的客户端，可直接粘贴导出内容，由 AI 为你导入。如果导出文件中包含酒精列且你希望保留该数据，请在导入前开启酒精追踪——关闭追踪时导入器会跳过该列，而且之后重新导入同一文件也不会补录这些数据。

演示

阅读背后的故事：我如何用一个 MCP 服务取代 MyFitnessPal 和其他应用

技术栈

• Bun — 运行时和包管理器
• Hono — HTTP 框架
• MCP TypeScript SDK v2（@modelcontextprotocol/server），使用 Zod 4 schema — 通过 Streamable HTTP 实现 Model Context Protocol，同时支持 2026-07-28 和 2025-11-25 两个协议修订版本
• Supabase — PostgreSQL 数据库 + 用户身份验证
• OAuth 2.0 — 用于 Claude.ai 和其他 MCP 客户端的身份验证：每个客户端动态注册客户端（RFC 7591），并严格匹配重定向 URI，强制使用 PKCE（S256），在令牌端点进行客户端身份验证（none、client_secret_post、client_secret_basic），授权码和刷新令牌绑定到签发给它们的客户端，每个授权响应都包含 iss（RFC 9207），客户端密钥、访问令牌、刷新令牌和授权码仅以 SHA-256 哈希形式存储。访问令牌有效期为 24 小时；刷新令牌自上次使用起有效期为 90 天，并在每次刷新时轮换；过期令牌和从未使用过的客户端注册每小时清理一次

MCP 工具

Tool	Description
log_meal	记录一餐的描述、类型、热量、宏量营养素、膳食纤维、总糖和添加糖、饱和脂肪和反式脂肪、钠（mg）、酒精、咖啡因（mg）及备注——可通过文字或餐盘照片记录；每个数值都会记录其来源
start_meal_import	打开聊天内 CSV 导入器：选择其他应用导出的文件，映射其列、预览并确认
bulk_import_meals	每次调用写入最多 50 条导入记录——逐条验证，并跳过重复项；只要时区未变，重新发送也安全
lookup_barcode	通过 Open Food Facts 根据条形码查询包装产品的标签营养信息，包括标签列出的添加糖（可从照片读取或手动输入；数据 © OFF contributors，ODbL）
search_foods	按英文名称搜索 USDA FoodData Central 中的通用食品；最多返回 10 个候选项及其 ID 和每 100 g 的宏量营养素
get_food_macros	根据通用食品的 ID 获取 USDA FoodData Central 数值，按每 100 g 显示或根据 amount_g 换算，并附上列出的份量
get_meals_today	获取今天记录的所有餐食，每餐占一行简要显示并附带其 ID；detail: "full" 会添加备注
get_meals_by_date	获取指定日期（YYYY-MM-DD）的餐食，每餐占一行简要显示；detail: "full" 会添加备注
get_meals_by_date_range	获取两个日期之间（含首尾）的餐食，每次调用最多 31 天；每餐占一行简要显示，detail: "full" 会添加备注
search_meals	按关键词（包括食材名称）搜索过往餐食，并按重复出现的变体分组显示已保存餐食（次数、最近记录时间、典型宏量营养素）
get_nutrition_summary	获取日期范围内的每日营养总量和目标进度，每次调用最多 92 天
get_digest	获取某个时段的摘要（昨天、今天截至目前、最近 7 天或 30 天）：热量和营养素与目标的对比、趋势、水分和体重、餐食或记录习惯，以及用户个人记录中的重点
update_meal	更新现有餐食的任意字段
delete_meal	按 ID 删除一餐
save_meal	为餐食命名并保存每份的数值及可选食材，以便稍后再次记录
log_saved_meal	按份数缩放并记录已保存的餐食；可将单项食材设为实际食用量或省略不计
get_saved_meals	列出已保存餐食的数值和食材，可按名称筛选
update_saved_meal	修改已保存餐食的名称、数值或食材；此前根据它记录的餐食不会改变
delete_saved_meal	删除已保存餐食；此前根据它记录的餐食及其数值不会改变
set_nutrition_goals	设置每日热量、宏量营养素、膳食纤维和水分摄入目标，以及总糖、添加糖、饱和脂肪、酒精、咖啡因和钠的摄入上限；还可选填目标体重
get_nutrition_goals	获取当前每日目标和上限
get_goal_progress	获取指定日期（默认为今天）的摄入量与目标和上限的对比，以及最新体重与目标的对比
log_water	以毫升记录一笔饮水量
get_water_today	获取今天的饮水总量和记录
get_water_by_date	获取指定日期的饮水量
delete_water	按 ID 删除一条饮水记录
log_weight	以 kg 或 lb 记录体重测量值（在服务端换算并存储）
get_weight_today	获取今天的体重记录
get_weight_by_date	获取指定日期的体重记录
get_weight_by_date_range	获取两个日期之间（含首尾）的体重记录，按天分组；每次调用最多 366 天
get_weight_trends	体重趋势：平滑后的趋势体重、每周变化率、最新体重、总体变化、最低/最高体重、目标进度；小组件可缩放查看 7 天、30 天、90 天、1 年或全部历史数据
update_weight	更新现有体重记录
delete_weight	按 ID 删除一条体重记录
set_weight_unit	设置首选体重单位（kg 或 lb；设为 null 可清除）
log_body_measurement	以 cm 或 in 记录卷尺测量值（腰围、臀围、颈围、胸围、肩围、上臂围、前臂围、大腿围、小腿围）
get_body_measurements	按天列出身体测量值，可选指定部位；默认显示最近 30 天，每次调用最多 366 天
update_body_measurement	更新测量值、单位、时间或备注（部位固定）
delete_body_measurement	按 ID 删除一条身体测量记录
set_length_unit	设置首选长度单位（cm 或 in；设为 null 可清除）
get_trends	获取 7/14/30 天的平均值、标准差、连续记录天数、最佳/最差日期；group_by 可按周/月/季度/年汇总日历周期平均值、每个记录日平均值，以及与当时生效目标的对比
get_meal_patterns	获取预先汇总的行为模式（早餐影响、晚餐时间过晚、周末与工作日对比、异常值）
export_all_data	将存储的所有个人数据导出——日志、已保存餐食和食材、每个营养素数值的来源、目标、个人资料、账户、遥测数据、应用连接和 Apple Health 同步记录——打包为一个包含 CSV 文件和 README 的 ZIP；链接有效期为 60 分钟
get_profile	一次调用获取时区（以及当地日期/时间）、小组件语言、体重和长度单位、小组件显示设置、酒精跟踪设置及 Apple Health 同步状态
set_timezone	设置用户的 IANA 时区（例如 America/Los_Angeles）
set_language	设置聊天内小组件（仪表板、图表）的 UI 语言——不影响 AI 回复所用的语言
get_current_time	获取用户时区中的当前日期和时间，以及 UTC 时刻——适用于上下文中没有时钟的宿主
set_widget_display	启用或禁用聊天内可视化小组件（仪表板、环形图、图表）；默认启用
set_alcohol_tracking	开启或关闭酒精跟踪（默认关闭），并选择美国标准杯数或英国酒精单位；关闭后会隐藏酒精数据，而不会将其删除
delete_account	永久删除用户的 Nutrition MCP 账户及其存储的所有用户数据

MCP 资源

URI	描述
nutrition://weekly-summary	滚动 7 天摘要（平均值与目标对比、表现最好／最差的一天），用于主动拉取

聊天内小组件

在支持 MCP Apps 的宿主中，这些工具也会在聊天中绘制卡片。每张卡片都包含与文本回答相同的数据：

• 营养摘要（get_nutrition_summary）和已记录餐食（log_meal、update_meal、log_saved_meal）：显示半圆热量仪表。对于单日，圆弧按餐次划分；对于日期范围，则显示平均值与峰值日期的对比。点击显示更多可查看营养素：每项都有自己的迷你仪表；展开后可查看其来源餐食和食材，日期范围还会显示按天排列的条带，以及按餐次划分的热量。列表中包含钠、饱和脂肪和反式脂肪。只有在设置目标后，才会显示已记录餐食卡片。
• 目标进度（get_goal_progress）：显示某天的摄入量与目标和限值的对比，以及最新体重与目标体重的对比。
• 趋势（get_trends）：提供 7／14／30 天切换选项和营养素切换器，并以柱状图展示；每种营养素对应一张卡片。
• 体重趋势（get_weight_trends）：显示一段时间内的体重变化，可缩放至 7 天、30 天、90 天、1 年或全部历史记录。
• 摘要（get_digest）：以可折叠分区展示某个时段的数据，包括热量和营养素与目标的对比、趋势、饮水和体重、餐食或记录习惯，以及重点信息。
• 导入（start_meal_import）：CSV 导入器。文件会在浏览器中读取、映射并预览，然后才会保存内容。

卡片会遵循宿主的浅色或深色主题，以及通过 set_language 设置的语言。卡片默认启用；set_widget_display 可将其关闭，文本回答不受影响。

自托管

如需了解 Cloudflare 托管选项和独立的 Workers 参考，请参阅 Cloudflare 托管和电子邮件身份验证。本指南区分了在容器中运行此 Bun/Supabase 应用与将较小的功能集改造为 Workers 和 D1。

0. 获取代码

git clone https://github.com/akutishevsky/nutrition-mcp.git
cd nutrition-mcp
bun install
cp .env.example .env   # fill in real values as you go through the steps below

需要 Bun 1.x（与 Dockerfile 的 oven/bun:1 基础镜像匹配；未固定具体次版本）。

bun run gen:all 会重新生成公开站点页面，不会启动服务器。

打造属于你自己的版本： 公开站点包含维护者的个人信息 — Google Analytics、Microsoft Clarity、Patreon/GitHub/联系方式链接，以及 nutrition-mcp.com 域名。运行 bun run gen:all 生成公开页面，然后运行 bun run depersonalize 一次性移除个人信息（经同意后才加载的分析代码片段、同意横幅和页脚中的“Cookie 设置”按钮，以及分析 CSP 主机、Support/Contact 部分、社交链接，并将域名替换为 your-domain.com 占位符）。运行 bun run depersonalize --dry 可预览而不写入文件。之后，换上你自己的 public/og.png、favicon.ico、favicon.svg、apple-touch-icon.png、icon-192.png 和 icon-512.png，将域名占位符替换为你的真实域名，并重写隐私政策和服务条款中的分析段落（src/copy/legal*.ts），其中仍列出了这两项服务。运行 bun run gen:all 会撤销对生成页面所做的修改 — 要重新生成，先修改它读取的源文件（在 scripts/site-partials.ts 中填写你自己的 GA_MEASUREMENT_ID / CLARITY_PROJECT_ID，analyticsHead() 仅会在访客接受同意横幅后加载这些内容；或者将 ANALYTICS_ENABLED 设为 false，以完全移除代码片段、横幅和按钮；并修改 src/routes.ts 中的 SITE），然后再次运行该命令。此脚本只会修改 public/ 下的生成文件、导入工具的支持邮箱地址、src/index.ts 和 src/security-txt.ts 中的 security.txt 联系方式（会将其清空，因此在你设置自己的联系方式之前，/.well-known/security.txt 会返回 404）— 不会修改此 README 或 SECURITY.md。如果要发布自己的分支，请根据你的部署重写 SECURITY.md，并编辑或删除此文件顶部附近的 Patreon 行以及 演示 中的 Medium 链接。

1. Supabase 设置

1. 创建一个 Supabase 项目。

2. 启用 Email Auth（Authentication → Providers → Email），并关闭电子邮件确认。

3. 应用数据库架构。完整架构位于 supabase/migrations/ 中。使用 Supabase CLI：

   supabase link --project-ref <your-project-ref>
   supabase db push
   

   这会创建应用所需的所有表、索引、RLS 策略和外键。无需本地 Postgres — 迁移会直接在托管项目上运行。

4. 从 Project Settings → API 复制 service role key，并将其用作 SUPABASE_SECRET_KEY。

2. 环境变量

变量	描述
SUPABASE_URL	你的 Supabase 项目 URL
SUPABASE_SECRET_KEY	Supabase 服务角色密钥（绕过 RLS）
OAUTH_CLIENT_ID	（可选，旧版） 预注册静态 OAuth 客户端的 ID。现在客户端会通过 POST /register 自行注册；此变量仅用于在旧客户端退役前维持旧连接正常工作
OAUTH_CLIENT_SECRET	（可选，旧版） 旧版静态 OAuth 客户端的密钥
ALLOWED_ORIGINS	（可选） 允许通过 CORS 调用 /mcp 的额外浏览器来源列表，以逗号分隔；无论端口如何，localhost/127.0.0.1 始终允许
GOOGLE_CLIENT_ID	（可选） 用于“使用 Google 登录”的 Google OAuth 客户端 ID
GOOGLE_CLIENT_SECRET	（可选） Google OAuth 客户端密钥
OFF_USER_AGENT	用于条形码查询的 Open Food Facts User-Agent，格式为 AppName (email)
USDA_API_KEY	（可选） 用于 search_foods 和 get_food_macros 的 USDA FoodData Central API 密钥；未设置时，这些工具会提示 USDA 数据尚未配置
PATREON_CLIENT_ID	（可选） Patreon OAuth 客户端 ID，用于在着陆页的 Support 部分显示近期帖子
PATREON_CLIENT_SECRET	（可选） Patreon OAuth 客户端密钥
PATREON_CAMPAIGN_ID	（可选） 用于获取帖子的 Patreon 活动 ID
PATREON_ACCESS_TOKEN	（可选） 创作者在 Patreon 客户端管理页面中的 Access Token——一次性引导种子值，见下文
PATREON_REFRESH_TOKEN	（可选） 创作者在同一页面中的 Refresh Token——一次性引导种子值，见下文
PUBLIC_BASE_URL	（可选） Apple Health 快捷指令指向的公开来源（例如 https://your-domain.example）。部署到 nutrition-mcp.com 以外的任何位置时都应设置；否则，在该部署上配对的手机会被发送到生产站点
HEALTH_SYNC_SHORTCUT_URL	（可选，构建时） 已发布的 Nutrition MCP Health 快捷指令的 https://www.icloud.com/shortcuts/… 链接，在 /apple-health 上显示为安装按钮。Dockerfile 构建参数，例如 NOINDEX；未设置时，页面会显示快捷指令即将推出
PORT	服务端口（默认值：8080）
NOINDEX	（可选） 任意非空值都会在每个响应中发送 X-Robots-Tag: noindex, nofollow，并从生成的页面中移除 Google Analytics、Clarity 和同意横幅（包括页脚中的“Cookie 设置”按钮），适用于开发或预发布部署。也必须在构建时设置，因为页面是在构建期间生成的
ADDED_SUGAR_REQUIRED_FROM	（可选） ISO-8601 时间点（日期，或带偏移量的日期时间）；从该时间点起，log_meal / update_meal 会拒绝未同时提供 added_sugar_g 的 sugar_g。未设置、为空或无法解析时，不启用此规则。请在首次宣传 added_sugar_g 的部署之后较长一段时间再设置，因为托管服务会缓存工具列表数天，而使用旧版列表的客户端无法发送该字段
仅用于旧版 — 全新部署无需设置这些，因为每个客户端都会通过 POST /register 注册自己的凭据。若要为旧版静态客户端设置可选的 OAUTH_CLIENT_* 键值对：

bun run generate-oauth-creds

或手动设置：

openssl rand -hex 16   # use as OAUTH_CLIENT_ID
openssl rand -hex 32   # use as OAUTH_CLIENT_SECRET

Patreon 帖子，一次性设置：PATREON_ACCESS_TOKEN / PATREON_REFRESH_TOKEN 只会在服务器启动时读取一次；如果 patreon_tokens 表仍为空，就会用它们初始化该表。从那以后，服务器会自行刷新并存储一对令牌，因此永久保留这两个变量也是安全的（之后每次启动都不会执行任何操作）。你无需手动操作数据库。

3. Google 登录（可选）

电子邮件／密码开箱即用。如还要提供 “使用 Google 继续”， 请按照 docs/google-auth-setup.md 创建 Google OAuth 客户端，在 Supabase 中启用 Google 提供方，并设置 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET。这会添加 POST /authorize/google 和 GET /auth/google/callback 路由 — 请参阅 API 端点。

开发

bun install
cp .env.example .env   # fill in your credentials — see Self-hosting above for what to put here
bun run dev             # regenerates public/ pages, then starts with hot reload on http://localhost:8080

public/ 下生成的页面（index、tools、privacy、terms、login、/alternatives、本地化镜像、sitemap.xml）是构建产物，不纳入 git 跟踪 — 它们会在每次 Docker 构建、CI 中，以及每次 bun run dev 启动时重新生成。--watch 只会在保存时重启 src/index.ts 进程，因此不会重新运行生成流程 — 修改 src/copy/、src/routes.ts 或 scripts/site-partials.ts 后，请自行运行 bun run gen:all 以应用更改。

测试与质量

bun test                # run the test suite
bun run format           # format with Prettier (4-space indentation)
bun run format:check     # verify the tree is prettier-clean
bun run typecheck        # typecheck src/

CI 会在每个 PR 上运行 format:check 和 typecheck；typecheck 的检查范围仅限 src/，因此测试文件或 scripts/ 下的类型错误不会被它发现。

开发聊天内小组件（public/widgets/）时，运行 bun run harness 可启动本地主机模拟器，让你无需真实 MCP 客户端即可测试小组件。

连接到 Claude.ai

1. 在 Claude 目录中打开 Nutrition MCP
2. 点击 连接
3. 按提示登录或注册
4. 完成 — Claude 现在可以使用你的营养工具

或者，在 自定义 → 连接器 下将 https://nutrition-mcp.com/mcp 添加为自定义连接器。之后若要重新连接，请使用相同的电子邮件和密码登录，以保留你的数据。

Apple Health 同步

可选的 iOS 快捷指令 Nutrition MCP Health 会将每日汇总数据复制到 iPhone 上的 Apple Health：卡路里（膳食能量）、蛋白质、碳水化合物、总脂肪、纤维和咖啡因；连接时选择加入后，还会同步水分摄入量。不会发送酒精，也不会发送钠、饱和脂肪、反式脂肪或糖。无需安装应用，也无需新增 MCP 工具——你的 AI 应用仍会继续记录数据，而快捷指令只会读取已完成的日期。设置指南（安装链接、连接、自动化和日常使用）请参阅 nutrition-mcp.com/apple-health（快捷指令发布后，安装链接会显示在该页面）；快捷指令的构建方式见 docs/apple-health-shortcut.md。

• **连接：**在 iPhone 上运行快捷指令。它会询问是否包含水分摄入量，以及是否也发送最近 7 天的数据，然后在 Safari 中打开登录页面——使用你的 AI 应用所用的同一账号登录。页面会将控制权交还给快捷指令，由它完成连接。连接链接只能使用一次，有效期为 30 分钟，并且只能由发起连接的 iPhone 完成连接。
• **同步内容：**仅包含已完成的日期。按你所在时区，日期会在次日凌晨 05:00 视为完成，因此昨天的数据会在今天 05:00 之后出现，而今天的数据不会进入 Health。每天每种类型会生成一条记录，时间为 12:00，标签为“Shortcuts”。每次同步都会回溯最近 7 个已完成的日期，因此错过早晨同步时，数据会自动补上。
• **后续更改：**如果向已发送的日期添加餐食，且该日期仍在这 7 天范围内，就会作为一条小额额外记录同步（12:01、12:02……）。Health 无法降低数值，因此删除或减少餐食后，Health 中的数值仍会偏高，快捷指令会显示提示，说明如何手动修正当天的数据。
• **运行时机：**每当其中一项自动化触发时运行——打开 Health 应用、停止闹钟，或者选择启用后插入电源时；也可以在快捷指令中选择 Sync now。
• **服务器保留的数据：**连接信息，以及 8 天内发送过的数据，这样每天只会发送一次，之后只会补充数据。这两项都会包含在你的数据导出文件中（health_sync.csv，以及 connections.csv 中的一行 health_sync）。如果 90 天内未同步，连接就会结束；连接后最迟 365 天也会结束。在快捷指令中选择 Disconnect，或删除账号，都会立即移除连接。Apple Health 中的数据永远不会被移除——这些数据保存在你的 iPhone 上。
• 你的个人资料时区决定每天何时结束。如果你从未设置过时区，则使用连接时 iPhone 报告的时区。get_profile 会显示同步是否已连接，以及已发送到哪一天的数据。

你的数据

export_all_data 会将账号的所有存储数据打包成一个 ZIP 文件，并通过有效期为 60 分钟的链接提供下载。每次导出都会替换上一次导出。ZIP 文件包含：

• meals.csv 和 meal_items.csv — 每餐及其食材，以及每项营养素数值的来源。meals.csv 使用导入器的列名，因此可以再次导入。
• saved_meals.csv 和 saved_meal_items.csv — 已保存的餐食及其食材。
• water.csv、weight.csv 和 body_measurements.csv — 所有记录。
• goals.csv 和 goals_history.csv — 当前目标和限值，以及它们的变更记录。
• profile.csv 和 account.csv — 设置和账号详情。
• telemetry.csv — 为该账号保留的工具调用日志。
• connections.csv — 已连接到该账号的应用，包括 Apple Health 同步链接。
• health_sync.csv — 最近 8 天发送到 Apple Health 的日期。
• README.txt — 时间戳使用的时区、以毫克为单位的列，以及可导入的文件。

每个时间戳旁边都有一个 timezone 列；即使文件没有数据行，也会包含表头。

故障排除

完整版提供 10 种语言，见 nutrition-mcp.com/tools#troubleshooting。简而言之：

• 无法连接或反复要求登录： 删除连接器，然后使用准确的 https://nutrition-mcp.com/mcp 重新添加，再使用之前相同的邮箱和密码（或 Google 账号）登录——你的数据属于账号，而非连接。只要至少每 90 天使用一次，连接就会保持有效。
• 登录页面显示 {"error":"session_expired"}： 页面有效期为 10 分钟，服务器重启时会重置；重新加载页面或重新开始连接。session_mismatch 表示你在与打开登录页面时不同的浏览器中完成了登录。
• 无法登录／忘记密码： 已有账号请使用 Sign in——邮箱或密码错误时会显示“Wrong email or password”，且绝不会创建新账号；Create account 仅供首次访问时使用。如果你使用 Google 注册，请选择 Continue with Google。目前尚无自助重置功能——请从账号绑定的邮箱地址发送邮件至 [email protected]。
• 重新连接后历史记录消失： 每个邮箱对应一个独立账号；请使用最初注册时使用的邮箱登录。
• AI 会回答，但不会记录： 检查该对话是否启用了连接器，明确提出记录请求，并批准工具权限提示。
• 餐食记录日期错误： 日期根据你的时区划分（设置时区前使用 UTC）。使用 set_timezone 设置时区；过去的记录会重新归类，但如果某条记录在时区错误时指定了具体时间，该时间点会保持不变——请使用 update_meal 更正。导入历史记录前请先设置时区：更改时区后重新导入其他应用的文件会再次添加这些记录（Nutrition MCP 导出文件可被识别，不会重复导入）。
• 没有图表或卡片： 小组件需要支持 MCP Apps 的宿主；调用 set_widget_display 后，请开始新对话。只有设置了目标后才会显示餐食记录卡片。
• 导入器无法打开或无法保存： 请让 AI 使用 bulk_import_meals 直接导入文件（会跳过重复记录，因此只要期间时区没有更改，重复发送也是安全的；请在首次导入前设置时区）。如果使用导入器面板并希望保留酒精列，请先开启酒精追踪；追踪关闭时，面板会跳过该列。
• “Rate limit exceeded”／“Too many failed authentication attempts”： 每个账号每分钟最多 60 次请求；登录页面每个网络每分钟最多 30 次请求。连续 20 次连接尝试被拒后，网络会暂停 5 分钟，最长可延长至 1 小时——通常是旧连接器在重试；请将其删除并重新添加。
• 条形码未找到或信息错误： 数据来自 Open Food Facts（8–14 位数字，不含咖啡因数据；只有产品标注了添加糖时才会提供，若 Open Food Facts 根据配料估算，则会注明）；找不到产品时，也可以通过名称或标签照片提供营养数据。
• 必须指定时间才能获取 USDA 数据： USDA FoodData Central 查询（search_foods、get_food_macros）由所有用户共用每小时配额。达到 USDA 限额后，或密钥的每小时配额即将用尽时，查询会暂停 60 分钟；每位用户每小时也最多可查询 30 次。暂停期间，过去 30 天内查询过的食物仍可使用。USDA 的名称为英文，请使用英文食物名称进行搜索。
• Apple Health 中尚无昨天的数据： 一天结束后，数据会在你所在时区次日凌晨 05:00 发送；之后进行的下一次同步（打开“健康”、停止闹钟或选择 Sync now）会将数据同步过去。每次同步都会覆盖最近 7 天的数据。
• Apple Health 中的数据比聊天记录多： Health 无法降低已有数值。请在“快捷指令”中前往“健康” → “浏览” → “营养” → （类型）→ “显示所有数据”，删除当天的记录，并手动输入正确总量。切勿使用“从快捷指令删除所有数据”——这也会删除其他快捷指令记录的数据。如果每天的数据看起来都翻倍，说明另一个应用也在写入相同类型的数据；请前往“健康” → “共享” → “App”将其中一个应用关闭。
• Apple Health 同步已停止： 手动运行 Nutrition MCP Health 查看原因。如果系统要求重新连接（90 天未同步、连接满 365 天或执行“断开连接”后），请在打开的页面中于 30 分钟内登录。如果只能手动同步，请检查自动化是否已开启并设为“立即运行”；如果通知提示某天的数据未同步到 Health，请允许“快捷指令”通过“健康” → “共享” → “App” → “快捷指令”写入所有营养类型。
• 导出链接无法使用： 链接会在 60 分钟后过期，且每次导出都会替换上一次导出；请重新生成链接。如果导出报告显示餐食数量为 0，而你原本预期有历史记录，通常表示你使用了不同的邮箱登录。
• 删除账号： delete_account 会在你确认后永久删除所有内容；如果需要留存副本，请先导出。
• 报告问题： 请在 GitHub Issues 报告 Bug（切勿提供密码）；安全问题请私下报告，具体说明见 SECURITY.md。

API 端点

端点	描述
GET /health	健康检查
GET /.well-known/oauth-authorization-server	OAuth 元数据发现（根路径和限定于 /mcp 的变体）
GET /.well-known/oauth-protected-resource	OAuth 受保护资源元数据发现（根路径和限定于 /mcp 的变体）
POST /register	动态客户端注册（RFC 7591）——按客户端注册，并强制校验重定向 URI
GET /authorize	OAuth 授权（显示登录页面）
POST /authorize/google	登录页面表单；重定向至 Google 的授权同意页面
GET /auth/google/callback	Google OAuth 回调——交换授权码并完成登录
POST /approve	登录/注册处理程序
POST /token	令牌交换——需通过客户端身份验证，并提供 redirect_uri 和 PKCE 验证器
GET /.well-known/security.txt	安全联系信息（RFC 9116）；Expires 每天向后滚动更新
GET /security.txt	301 重定向至 /.well-known/security.txt
GET /favicon.ico	服务图标
GET /favicon.svg	网站图标（SVG）
GET /api/stats	首页总计数据（餐食、卡路里、宏量营养素、时区），仅提供汇总数据
GET /api/patreon-posts	首页「支持」板块显示的最新 Patreon 帖子
GET /api/github-stars	网站 GitHub 按钮显示的缓存 GitHub 星标数
POST /api/v1/health-sync/start	Apple Health 同步：从快捷指令启动连接（返回连接链接）
GET /health-sync/connect/:id	Apple Health 同步：为该连接请求打开常规登录页面
GET /health-sync/callback	Apple Health 同步：登录回调；将认领码返回给快捷指令
POST /api/v1/health-sync/claim	Apple Health 同步：使用认领码和设备密钥交换同步令牌
GET /api/v1/health-sync/pending	Apple Health 同步：待记录的已结束日期总计（Bearer nmhs_… 令牌）
POST /api/v1/health-sync/ack	Apple Health 同步：记录快捷指令已写入的数据（Bearer 令牌）
POST /api/v1/health-sync/revoke	Apple Health 同步：断开连接（Bearer 令牌）
ALL /mcp	MCP 端点（需身份验证）

部署

该项目包含一个用于基于容器部署的 Dockerfile。

1. 将你的代码库推送到托管服务提供商（例如 DigitalOcean App Platform）
2. 设置上文列出的环境变量
3. 应用会自动检测 Dockerfile，并在端口 8080 上部署
4. 将你的域名指向已部署的 URL

支持与安全

• **帮助、错误报告、功能请求：**打开 GitHub issue 或发送邮件至 [email protected]。
• **安全漏洞：**请勿公开提交 issue。请通过 GitHub 私密漏洞报告 或发送邮件至 [email protected] 私下报告 — 详见 SECURITY.md。机器可读的联系方式：https://nutrition-mcp.com/.well-known/security.txt
• **删除账户 / 您的数据：**使用 delete_account 和 export_all_data 工具，或发送邮件至上述地址。详见隐私政策。

食品数据来源

营养数据来自三个来源，每项营养素数值都会记录其来源（用户、标签或条码记录、USDA，或估算值）。聊天内的小组件会在每餐和每种食材的数值旁以标签显示来源，导出内容则会在 nutrient_sources 中包含来源信息。只有当数值与所记录的份量对应的数据相符时，才会标记为 USDA 或 Open Food Facts；服务端会对此进行检查，因此数值不能标注与其不符的来源。

USDA FoodData Central（search_foods、get_food_macros）涵盖 Foundation、SR Legacy 和 Survey（FNDDS）数据类型中的通用非品牌食品，按每 100 g 提供数值，并根据实际食用克数和 USDA 列出的份量进行换算。其数据仅提供英文，因此请使用英文食品名称进行搜索。USDA 未记录的食品营养素会标记为未记录，绝不会显示为零。请求会将搜索词（经过清理且最多 200 个字符）或 FoodData Central ID 连同本服务的密钥发送至 USDA API，不会发送用户标识符。

FoodData Central 的建议引用格式，来自 fdc.nal.usda.gov：

U.S. Department of Agriculture, Agricultural Research Service, Beltsville Human Nutrition Research Center. FoodData Central. [Internet]. [cited 2026-10-10]. Available from https://fdc.nal.usda.gov/.

Nutrition MCP 未获 U.S. Department of Agriculture 认可。

Open Food Facts（lookup_barcode）通过条码查询包装食品的产品数据。产品数据 © Open Food Facts 贡献者，依据 Open Database License (ODbL) 提供。每项查询结果都会注明 Open Food Facts 和许可证。

没有对应记录的数值为估算值，或来自用户分享的标签。

许可证

MIT