foodvisor-mcp

一个远程 Model Context Protocol 服务器，将 Foodvisor 营养 API 暴露给 LLM 代理（Claude、Cursor 等）。你可以直接从你的助手处搜索食物、记录膳食、获取进度和宏量营养素。

免责声明。 本项目是非官方的。它通过逆向工程使用 Foodvisor 的私有移动 API，且未得到 Foodvisor 的认可。使用风险自负；端点可能会在不另行通知的情况下更改。

功能

• 🥗 目录搜索：包含卡路里、宏量营养素、品牌、图片、Nutriscore。

• 📒 记录膳食：记录（早餐/午餐/晚餐/零食/自定义_*）膳食，支持数量和份量倍数。

• 📊 每日摘要：服务器端汇总卡路里和宏量营养素与你的目标对比。

• 📈 进度：每日卡路里、体重和评分历史记录（约 90 天）。

• 🔥 连续记录：当前的连续记录天数及可用的冻结天数。

• 💧 水分记录。

• 👤 个人资料与营养目标：按工作日设置的卡路里/宏量营养素目标。

• 🔐 OAuth 2.1 + PKCE：支持动态客户端注册，可作为一键式 Claude 连接器使用。

• 🔄 无状态多用户：令牌是自包含的（无需数据库）。Foodvisor 刷新令牌在 OAuth 签发的 JWT 中进行加密（AES-256-GCM）。

• ♻️ 自动访问令牌刷新：具备内存缓存和并发请求保护。

可用的 MCP 工具

Docker 快速入门

git clone https://github.com/cldt-fr/foodvisor-mcp.git
cd foodvisor-mcp
docker compose up -d

服务器现在监听 http://localhost:3000/mcp。健康检查端点位于 /health。

若要在公共域名的反向代理（Caddy、Traefik、nginx）后运行，只需在 3000 端口前终止 TLS 即可。

身份验证

foodvisor-mcp 支持两种身份验证方式，两者均由相同的底层凭据支持——即你的 Foodvisor 刷新令牌：

1. OAuth 2.1（推荐） — 服务器是一个完整的 OAuth 授权服务器，支持动态客户端注册和 PKCE。兼容的 MCP 客户端（Claude、Cursor 等）会自动处理流程：它们发现授权端点、注册自身并打开一个登录页面，你在该页面粘贴一次 Foodvisor 刷新令牌。随后服务器会签发自己的 JWT，其中包含 AES-256-GCM 加密的刷新令牌。

2. 直接 Bearer（高级用户） — 直接将你的 Foodvisor 刷新 JWT 作为 Authorization: Bearer … 传递。适用于脚本或快速测试。服务器会检测令牌格式并像之前一样进行代理。

无论哪种方式，服务器都不会存储任何用户状态：OAuth 签发的 JWT 是自包含的，而传统模式纯粹是透传。

获取你的 Foodvisor 刷新令牌

Foodvisor 仅通过 iOS 上的 Apple 登录进行身份验证——没有公共的 OAuth 或密码端点。使用配置为 HTTPS 中间人的 Charles Proxy（或 Proxyman、mitmproxy 等）在真实的 iPhone 上捕获 POST /user/auth/ 响应：

1. 在 iPhone 上安装 Charles 的根证书并启用完全信任。

2. 强制退出并重新打开 Foodvisor 应用，然后登录。

3. 查找 POST https://api.foodvisor.io/api/6.0/ios/FR/fr_FR/user/auth/ 请求。JSON 响应包含 tokens.refresh —— 这就是你的长效凭据（约 6 个月）。

刷新令牌可以完全访问你的营养历史记录。请像对待密码一样对待它们。

配置 MCP 客户端

Claude (网页 / 桌面端 / Code) — OAuth

将服务器添加为连接器，使用其公共 /mcp URL（例如 https://foodvisor-mcp.example.com/mcp）。Claude 将：

1. 在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server 发现 OAuth 元数据。

2. 通过 POST /register 注册自身。

3. 在浏览器中打开 /authorize 页面。在表单中粘贴你的 Foodvisor 刷新令牌并提交。

4. 将返回的代码交换为长效访问令牌（默认 30 天）。

之后，你就可以直接从 Claude 使用这些工具了。当访问令牌过期时，Claude 会重新运行该流程。

直接 Bearer（任何支持流式 HTTP 的 MCP 客户端）

{
  "mcpServers": {
    "foodvisor": {
      "url": "https://foodvisor-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_FOODVISOR_REFRESH_TOKEN>"
      }
    }
  }
}

本地开发

需要 Node ≥ 22。

npm install
npm run dev      # tsx watch on $PORT (default 3000)
npm run typecheck
npm run build && npm start

项目布局

src/
├── index.ts                  # Node http server + per-request MCP transport + OAuth routes
├── env.ts                    # zod-validated env vars
├── auth/
│   ├── extract.ts            # Bearer parsing — accepts OAuth JWT and legacy Foodvisor refresh
│   └── token-cache.ts        # Foodvisor access-token cache + refresh
├── oauth/
│   ├── jwt.ts                # HS256 sign/verify + AES-256-GCM encrypt/decrypt
│   ├── store.ts              # in-memory clients + auth codes (TTL)
│   ├── login.ts              # HTML login page (paste refresh token)
│   ├── handlers.ts           # /register, /authorize, /token handlers
│   └── metadata.ts           # /.well-known/* metadata builders
├── foodvisor/
│   ├── client.ts             # fetch wrapper with 401 retry
│   ├── endpoints.ts          # typed endpoint helpers
│   └── types.ts              # response shapes
└── mcp/
    ├── server.ts             # createMcpServer(ctx)
    └── tools/                # one file per tool group
        ├── food.ts
        ├── meal.ts
        ├── progress.ts
        ├── trackers.ts
        └── profile.ts

HTTP 服务器被有意保持最小化（无 Express/Hono）——每个 POST /mcp 都会启动一个新的 McpServer，绑定到调用者的 userId/refreshToken 和一个无状态的 StreamableHTTPServerTransport。

环境变量

使用以下命令生成稳定的密钥：

openssl rand -base64 48

安全说明

• 服务器是 Foodvisor 的受信任代理：任何持有有效 Foodvisor 刷新令牌的人都可以使用它来读取和写入该用户的营养数据。在生产环境中，请在 /mcp 端点前使用 HTTPS，如果它是公开暴露的，请考虑使用 IP 白名单。

• 令牌仅保留在进程内存中。它们永远不会持久化到磁盘。

• 令牌缓存以 JWT 的 user_id 为键，因此来自同一用户的并发请求共享同一个访问令牌；并发刷新尝试通过进行中的映射进行合并。

路线图

• 一旦上传端点被逆向工程，将支持基于照片的膳食识别（Foodvisor 的杀手级功能）。

• 活动记录、体重记录、自定义食谱和收藏夹。

• 可选的持久化令牌存储，以提高重启后的弹性。

贡献

欢迎在 https://github.com/cldt-fr/foodvisor-mcp 提交 Issue 和 PR。请不要提交请求帮助逆向工程 Foodvisor 端点的 Issue；请使用 Charles/Proxyman 自行捕获并贡献类型化的包装器。

许可证

MIT — 见 LICENSE。