cronometer-api-mcp

cronometer-api-mcp

面向 Claude.ai、ChatGPT 和 Grok 的托管版本即将推出。 加入候补名单 →

一个用于 Cronometer 营养追踪的 MCP（Model Context Protocol） 服务，基于逆向工程分析的移动端 REST API 构建。

与 cronometer-mcp 不同，后者采用全面的 GWT-RPC 方案访问 Cronometer 的 Web 后端；本服务使用与 Cronometer Android 应用相同的 JSON REST API，提供简洁的载荷和稳定的版本化端点。

功能

• 食物日志 —— 包含食物名称、分量和餐食组的日记条目
• 营养数据 —— 每日宏量／微量营养素总量和营养评分，并提供各营养素的置信度
• 食物搜索 —— 搜索 Cronometer 食物数据库并获取详细的营养信息
• 日记管理 —— 添加／移除条目、复制日期、标记日期为已完成
• 自定义食物 —— 创建带有自定义营养数据的食物
• 宏量营养素目标 —— 查看每周计划和已保存的模板
• 禁食 —— 查看历史记录和汇总统计数据
• 生物指标 —— 查看指定日期范围内的体重、体脂、心率及其他追踪指标

快速开始

1. 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 设置凭据

export CRONOMETER_USERNAME="[email protected]"
export CRONOMETER_PASSWORD="your-password"

可选：双重身份验证

如果账户启用了双重身份验证，除非请求中包含当前的 6 位代码，否则 /api/v2/login 会返回 TOTP_CODE_REQUIRED。向服务提供 Cronometer 在设置双重身份验证时显示的 base32 密钥（即扫描到身份验证器应用中的同一密钥），服务便会在每次登录时自行生成代码（RFC 6238、SHA-1、30 秒周期）：

export CRONOMETER_TOTP_SECRET="ABCD EFGH IJKL MNOP QRST UVWX YZ23 4567"

密钥中可以包含空格，也可以使用小写字母。未启用双重身份验证的账户请勿设置此项。

可选：覆盖账户时区

日记条目使用 Cronometer 账户的时区标记，服务会在登录时报告该时区。如果时区有误（例如，较旧版本曾重置时区），你可以强制指定一个 IANA 时区，而无需更改账户设置：

export CRONOMETER_ACCOUNT_TZ="America/Los_Angeles"

设置后，此时区优先于登录时报告的值和任何缓存的会话，因此也会覆盖过期的缓存时区。

3. 配置 MCP 客户端

uvx 会按需下载并运行服务，无需单独安装。

OpenCode（opencode.json）

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cronometer": {
      "type": "local",
      "command": ["uvx", "cronometer-api-mcp"],
      "environment": {
        "CRONOMETER_USERNAME": "{env:CRONOMETER_USERNAME}",
        "CRONOMETER_PASSWORD": "{env:CRONOMETER_PASSWORD}",
        "CRONOMETER_TOTP_SECRET": "{env:CRONOMETER_TOTP_SECRET}",
        "CRONOMETER_ACCOUNT_TZ": "{env:CRONOMETER_ACCOUNT_TZ}"
      },
      "enabled": true
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "cronometer": {
      "command": "uvx",
      "args": ["cronometer-api-mcp"],
      "env": {
        "CRONOMETER_USERNAME": "[email protected]",
        "CRONOMETER_PASSWORD": "your-password",
        "CRONOMETER_TOTP_SECRET": "your-base32-key",
        "CRONOMETER_ACCOUNT_TZ": "America/Los_Angeles"
      }
    }
  }
}

可用工具

食物日志与营养

工具	描述
get_food_log	指定日期的日记条目，每项均附有食物名称、来源、份量计量单位／数量，以及该食物在该条目中的各营养素含量；此外还包含 energy_summary（目标／摄入／剩余千卡）和 nutrition_summary（所有追踪营养素的摄入总量）
get_daily_nutrition	Cronometer 追踪的所有营养素的宏量和微量营养素摄入总量
get_nutrition_scores	分类评分（维生素、矿物质等），包含各营养素的摄入量和置信度

食物搜索与详情

工具	描述
search_foods	按名称搜索 Cronometer 食物数据库
get_food_details	食物的完整营养档案和份量规格

日记管理

工具	描述
add_food_entry	将一份食物记录到日记中
remove_food_entry	删除一条或多条日记条目
add_custom_food	创建自定义食物，并指定营养信息和可选条形码
update_custom_food	就地编辑自定义食物：名称、营养信息、份量或条形码
delete_custom_food	停用自定义食物，使其不再显示在搜索结果和 Custom Foods 列表中（现有日记条目会保留）
add_recipe	根据按 ID 和克重引用的现有食物创建食谱
import_recipe	根据自由文本食材列表创建食谱；Cronometer 会将每行内容匹配到数据库食物，并将数量换算为克
copy_day	复制前一天的所有条目
mark_day_complete	将日记中的某一天标记为已完成或未完成

目标与追踪

工具	描述
get_macro_targets	每周宏量营养素计划和已保存的目标模板
get_fasting_history	指定日期范围内的禁食记录
get_fasting_stats	汇总禁食统计数据
list_biometrics	列出可追踪的生物特征指标及其单位
get_biometrics	指定日期范围内的生物特征时间序列（例如体重、体脂）

所有日期参数均使用 YYYY-MM-DD 格式；未提供时默认为今天。

相对日期与近期日期

get_food_log、get_daily_nutrition 和 get_nutrition_scores 的 date 参数也接受 "today"、"yesterday" 和 "N days ago"。这些值会在调用时根据你的 Cronometer 账户时区解析，因此 Claude 可以传入相对日期，而不必依赖长时间对话中先前提到的日期。

get_food_log 和 get_daily_nutrition 接受 days（1–31，默认值为 1），从包含在内的结束日期 date 起向前计数：

get_food_log(date="yesterday")
get_nutrition_scores(date="3 days ago")
get_daily_nutrition(days=3)  # Last 3 days, including today
get_daily_nutrition(date="yesterday", days=3)  # Previous 3 complete calendar days
get_food_log(days=7)  # Recent meals, including today

若要查询“过去几天的卡路里”，请使用 get_daily_nutrition(days=3)。 单日响应会保留现有结构。多日响应包含 start_date、end_date 和按日期从早到晚排列的每日结果 days 列表。 返回的日期始终为具体的 YYYY-MM-DD 值。

传输方式

仅支持 stdio。对于远程／托管使用场景，stdio 服务会由 supergateway 包装（参见 Dockerfile）， 由它负责 HTTP 监听，并在 /mcp 暴露 MCP streamable-HTTP。该服务没有内置身份验证——任何远程部署都必须置于具备身份验证功能的网关或反向代理之后。

开发

本地开发时，将 .env.example 复制为 .env 并填写凭据：

cp .env.example .env
# edit .env
uv run cronometer-api-mcp

CLI 启动时会自动加载 .env（仅为开发提供便利）。实际环境变量始终优先于 .env，因此不会影响生产部署和 MCP 客户端的 env 配置块。

工作原理

此服务与 mobile.cronometer.com 通信——这是 Cronometer Android／Flutter 应用使用的同一 REST API。该 API 通过以下方式逆向分析得出：

1. 对 APK 中的 libapp.so（Dart AOT 快照）进行静态分析，以发现端点名称
2. 通过 Frida + mitmproxy 拦截流量，以捕获准确的请求／响应格式
3. 针对线上 API 反复试验，以确认负载结构

该 API 使用两种协议：

• v2（POST /api/v2/*）——基于 JSON 请求体的身份验证，用于大多数操作（食物搜索、日记读写、营养、禁食、宏量营养素、生物特征）
• v3（DELETE /api/v3/user/{id}/*）——基于请求头的身份验证（x-crono-session），用于删除日记条目

食谱导入是唯一的异步操作：import_recipe 会返回一个任务 ID，然后需要持续轮询 poll_async_result，直到服务端报告进度达到 100% 并附加解析后的食材。

Python API

你可以直接使用客户端：

from cronometer_api_mcp.client import CronometerClient
from datetime import date

client = CronometerClient()

# Search for foods
results = client.search_food("chicken breast")

# Get food details
food = client.get_food(results[0]["id"])

# Log a serving
client.add_serving(
    food_id=food["id"],
    measure_id=food["defaultMeasureId"],
    grams=200,
)

# Get today's diary
diary = client.get_diary()

# Import a recipe from a free-text ingredient list
recipe = client.import_recipe("one hot dog\nketchup\nbun")
print(recipe["food_id"], recipe["ingredients"])

# Parse without saving, to review the matches first
preview = client.import_recipe("2 tbsp olive oil\n200g chicken", save=False)

# Get nutrition scores
scores = client.get_nutrition_scores()

许可证

MIT