fatsecret-mcp

fatsecret-mcp

通过手机与 Claude 或 ChatGPT 对话，即可将食物记录到你的 FatSecret 日记中。你会先看到草稿，只有在你确认后才会保存。

https://github.com/user-attachments/assets/44dfd991-5434-47ad-8b84-bcad24415a1f

晚餐照片、Claude 提出的草稿、一个「是」、当天的记录，以及 FatSecret 应用中的新条目。

fatsecret-mcp 是一个可自托管的 MCP 服务。它将 Claude（或在 Operator 启用后使用的 ChatGPT）连接到你自己的 FatSecret 食物日记，也就是你在 FatSecret 应用中看到的日记。Claude 可以根据你的每日卡路里和宏量营养素目标，读取某一天或数周的记录。它可以在 FatSecret 目录中查找食物，并根据描述或照片拟定记录草稿。每份草稿都会显示份量、卡路里、宏量营养素、建议的餐食，以及添加后的每日情况。如果目录中没有包装产品，只需提供一张营养标签照片即可。错误的记录也可以通过草稿的方式修正或删除。

一个服务即可供整个家庭使用：几个人各自登录自己的 FatSecret 账户。没有公共实例，因此你需要自行运行。

此项目为非官方项目，与 FatSecret、Anthropic 或 OpenAI 均无关联，也未获其认可，且不构成医疗或饮食建议。

由 fatsecret Platform API 提供支持

你可以提出的请求

该服务为 Claude 提供五种工具。你无需亲自调用它们，只需对话即可。

search_foods

在目录中查找可记录的食物及其份量。

你： 一杯煮熟的茉莉香米有多少卡路里？

Claude： FatSecret 中有「茉莉香米（煮熟）」：1 杯（158 g）含 205 kcal、4.3 g 蛋白质、0.4 g 脂肪和 44.5 g 碳水化合物。

draft_entries

拟定记录草稿，不会写入任何内容。

你： （一盘食物的照片） 把它记作午餐。

Claude： 这是今天午餐的草稿：

• 韩式牛肉拌饭，1 碗（480 g）：640 kcal、32 g 蛋白质、21 g 脂肪、80 g 碳水化合物

我按餐馆份量的一碗进行了估算。添加后，你的摄入量将达到 1,420 / 2,200 kcal，蛋白质达到 78 / 140 g。要保存吗？

confirm_draft

写入你已批准的草稿。

你： 好。

Claude： 已保存。韩式牛肉拌饭已记入你 FatSecret 日记中的午餐。

get_diary_day

读取某一天的记录、总量以及剩余目标。

你： 今天还剩多少？

Claude： 你已摄入 1,420 kcal。还剩 780 kcal、62 g 蛋白质、18 g 脂肪和 95 g 碳水化合物。

get_period_summary

读取最多 31 天的每日总量。

你： 和前一周相比，我这周情况如何？

Claude： 这周你平均每天摄入 2,050 kcal 和 128 g 蛋白质；上周则是 2,240 kcal 和 117 g 蛋白质。这周有两天超过了卡路里目标，而上周有四天超标。

以上数字仅为示例。

如何记录一餐

sequenceDiagram
    actor U as You (Claude app)
    participant C as Claude
    participant S as fatsecret-mcp
    participant F as FatSecret API
    U->>C: photo + "log this as lunch"
    C->>S: search_foods
    S->>F: foods.search, food.get
    C->>S: draft_entries
    S-->>C: draft (amounts, kcal, macros, meal, the day after adding)
    C-->>U: shows the draft
    U->>C: "yes"
    C->>S: confirm_draft(draft_id)
    S->>F: food_entry.create, one per item
    S-->>C: saved entries

草稿由服务端签名，并在 30 分钟后过期。只有草稿对应的人才能确认。在 Claude 的连接器设置中，将 confirm_draft 保持为“需要批准”，这样每次写入都会先征求你的同意。

目录中没有的产品

免费的 FatSecret API 密钥只能访问美国目录，且内容为英文。大多数本地产品和品牌产品都不在其中。遇到这些产品时，Claude 会请你提供营养成分标签的照片，或者让你输入标签上的数值。服务端会将该产品记录为替代品：选取最接近的目录食品，并按热量与标签相符的份量记录，同时使用产品自身的名称。

flowchart TD
    S[Claude searches the catalog] --> Q{Found?}
    Q -- yes --> E[Normal food entry]
    Q -- no --> P["You send a photo of the label<br/>or type its values"]
    P --> V[Claude reads the calories and macros]
    V --> M["The server picks the closest catalog food<br/>and sets the amount so calories match"]
    M --> N[Entry saved under the product's own name]

热量与标签完全一致，但宏量营养素只能大致匹配，有时偏差还很明显。这是因为要把美国目录以外的产品映射到美国目录中的产品。日记条目无法单独记录热量或宏量营养素；它只能指向目录中的食品，并采用该食品的数值。免费密钥无法创建食品，因此服务端会选择宏量营养素最接近标签的美国食品。你的产品在美国目录中通常找不到宏量营养素完全一致的食品，因此没有更接近的选择。草稿会在你确认前显示标签上的数值、记录的数值及其差异；在 FatSecret 应用中打开该条目的详情，还能看到其对应的目录食品。

如果标签上的热量与宏量营养素对不上，服务端会拒绝该标签，以此识别照片读取错误或把 kJ 当成 kcal 的情况。服务端不会记住替代品：下次 Claude 会从对话中复用标签，或者再次询问。重复记录日记中的替代品时，会保留其名称和近似的宏量营养素数值。

如果你经常记录某种产品，在 FatSecret 应用中添加一次，就能在那里获得准确数值。之后，Claude 就可以从你的日记中重复记录它。

重复记录之前的一餐

你： 和昨天的早餐一样。

Claude： 昨天的早餐是：

• 燕麦片，80 g：300 kcal
• 2% 脂肪牛奶，250 ml：125 kcal
• 希腊酸奶，150 g：90 kcal

今天也都一样吗？还是要去掉某样食物或调整份量？

你： 不要酸奶，牛奶减半。

Claude： 这是从昨天重复记录的草稿：燕麦片，80 g；2% 脂肪牛奶，125 ml，总计 362 kcal。要把它记为今天的早餐吗？确认后我就保存。

Claude 会读取之前某天的记录，并为你保留的条目起草记录，无需搜索目录。服务端会从你的日记中复制每个条目的食品、份量、名称和营养数据，并在你调整份量时按比例换算；份量始终以克或 ml 显示。即使是目录无法返回的产品（例如你在 FatSecret 应用中添加的产品）以及替代品，也同样适用；替代品会保留产品名称，无需再次提供标签。如果某个份量记录时未使用克或 ml，例如“2 片”，系统会查询一次并以克显示；如果无法确定重量，则会按原样重复记录该条目。

修正或撤销一条记录

你： （刚保存完） 撤销。

Claude： 这是草稿：从今天的午餐中删除牛肉拌饭，1 碗（480 g），640 kcal。删除后，你将摄入 780 / 2,200 kcal。删除的记录无法恢复，只能重新记录。要删除吗？

你： 等等，保留吧，刚才其实是 300 g。

Claude： 这是新草稿：牛肉拌饭，1 碗（480 g）→ 300 g，640 → 400 kcal，仍属于午餐。要保存更改吗？

草稿也可以修改日记中已有的记录，包括你在 FatSecret 应用中记录的内容：更改克或 ml 数量、改成同一天的另一餐，或更换名称。也可以删除记录。每项更改都会显示修改前后的记录，以及修改后每天的情况。只有你确认后才会进行更改。对于“撤销”，Claude 会删除上次保存时写入的记录。其他情况下，它会先读取当天的记录；如果不确定你指的是哪一条，就会先询问。

FatSecret 无法将一条记录改成另一种食物或移到另一天。因此，“那是鸡腿肉，不是鸡胸肉”或“那是昨天的”会变成一份草稿：添加正确的记录，并删除错误的记录。新记录会先保存，因此如果中途出错，你看到的会是重复记录，而不是缺失记录。最多可以修改一年前的记录。

它做不到什么

• 它无法查询条形码、波兰目录等地区目录或自定义食物。免费密钥只能访问美国目录，因此 Claude 会用英语搜索。记录仍会以你使用的语言和名称保存，并附上一条简短备注，说明该食物匹配自美国目录，例如“波兰圆面包（美国目录）”；草稿会在旁边显示目录中的名称。
• 它不追踪体重、运动或食谱，只记录食物。
• 它不服务陌生人。它没有公共服务，每个服务都有固定的用户名单。

自行运行

家庭服务有一位运营者，负责部署服务并添加其他人。家中每个人都要通过运营者登录 FatSecret 一次，然后将该服务作为自定义连接器添加到自己的 Claude 账户，或者在运营者启用后添加到 ChatGPT。

flowchart LR
    A["Anna's phone (Claude)"] --> CL[Claude connector]
    J["Jan's phone (Claude)"] --> CL
    CL -->|"each signs in with their own ID and password"| S[fatsecret-mcp on your server]
    O[Operator] -->|"add-user, check"| S
    S -->|"one FatSecret token per person"| F[FatSecret API]
    F --> D[("each person's own diary, the same as in the FatSecret app")]

你需要：

• 自己的 FatSecret Platform API 密钥。在 platform.fatsecret.com 注册；免费 Basic 计划就够用。使用该服务即表示接受 FatSecret 的 API 条款。此项目不提供密钥；
• 一个支持 HTTPS 的容器托管平台，用于运行服务，例如 Railway；
• 每个人都需要一个 Claude 或 ChatGPT 账户，且其计划支持自定义连接器。

简要步骤：

1. 创建一个 .env，填入你的 FatSecret 密钥和签名密钥，然后为每个人运行一次 uvx --env-file .env fatsecret-mcp add-user（参见设置说明）。
2. 使用这些值部署镜像 ghcr.io/jaronskijakub/fatsecret-mcp（参见部署说明）。
3. 在 Claude 中，将 https://<your-server>/mcp 添加为自定义连接器并登录（参见连接器说明）。

如需先在自己的电脑上试用，可通过 Claude Code 使用 stdio 运行；设置说明也介绍了这一方法。请求配额、请求节奏和缓存见限制说明，信任模型见 SECURITY.md。

与 ChatGPT 搭配使用

ChatGPT 的登录方式与 Claude 相同，使用相同的用户 id 和连接器密码，并使用相同的五种工具。默认情况下，此功能处于关闭状态。Operator 将 FATSECRET_MCP_CLIENTS=claude,chatgpt 设置后重新部署，即可启用。

之后，每个人都可以在 ChatGPT 中添加 https://<your-server>/mcp 作为自定义连接器。ChatGPT 仅在部分套餐的开发者模式中提供自定义连接器；OpenAI 的开发者模式文章对此有说明。同时使用这两款应用的人需要分别登录；退出登录时，两边都会退出（连接器）。本页的示例来自 Claude。

ChatGPT 有时会在已确认的更改或移除操作到达服务之前，以“此工具调用已被 OpenAI 的安全检查拦截”为由阻止该操作，但添加条目不受影响。此时，你的饮食日记不会有任何变化。请在新聊天中重试，或使用 Claude 或 FatSecret 应用进行更改。

文档

• 设置：配置、添加用户、设置用户选项，以及使用 Claude Code 在本地运行。
• 部署：Railway、其他容器托管平台、Docker，以及自行构建镜像。
• 连接器：将服务添加到 Claude 或 ChatGPT、登录，以及让用户退出登录。
• 限制：每日配额、调用间隔、搜索、草稿和输入大小。
• 更新日志：各版本的更改内容。

请通过 SECURITY.md 报告漏洞；该文件也介绍了信任模型以及各类数据的存储位置。

路线图

• 为持有 FatSecret Premier 密钥的用户支持自定义食物，以便使用准确的营养值记录品牌产品，而不是用替代项。
• 对于美国目录中缺少的产品，支持通过名称或条形码查询 Open Food Facts。
• 按名称搜索自己的食物。目前，饮食日记中的任何条目都可以从记录当天重复添加，但尚不能搜索经常记录的产品；从整本饮食日记中读取这些产品会产生过多的 API 请求，因此需要另寻方案。
• 记住通过标签记录的产品，以便在饮食日记中没有重复记录时，无需再次提供照片就能使用替代项。这需要持久化存储。
• 在 Claude 中提供原生确认对话框，用于保存草稿，而不是在聊天中回复“是”。

开发

uv sync
uv run ruff check && uv run ruff format --check
uv run pyright
uv run pytest

测试不会调用 FatSecret，而是重放 tests/fixtures/fatsecret/ 中记录的响应。选择加入的冒烟测试会读取你的真实饮食日记：FATSECRET_LIVE_SMOKE=1 uv run --env-file .env pytest tests/test_live_smoke.py。容器测试的说明见部署。

要发布新版本，请使用 uv version X.Y.Z 设置版本，并在 server.json 的两个位置设置该版本，然后在 CHANGELOG.md 中添加一条注明日期的记录；tests/test_package.py 会检查这些版本是否一致。将该提交推送到 main 并等待 CI 完成，CI 会发布镜像。然后推送标签 vX.Y.Z。发布工作流会检查 CI 是否已在 main 上针对该提交通过，构建并检查软件包，将版本标签添加到该提交对应的镜像，将软件包发布到 PyPI，并根据更新日志条目创建 GitHub 发布。在公开仓库中，它还会将 server.json 发布到 MCP 注册表。

许可证

MIT