cronometer

cronometer-mcp

一个 MCP（Model Context Protocol） 服务，可访问你的 Cronometer 营养数据。通过 Claude、Cursor 或任何兼容 MCP 的客户端，获取详细的食物记录、每日宏量营养素和微量营养素汇总，并管理日记条目、禁食、生物特征数据和重复食物。

需要 Cronometer Gold 账户（或任何支持网页登录的付费套餐）。

功能

• 食物记录 — 单条食物记录，包含完整的宏量营养素和微量营养素明细
• 每日营养 — 每日卡路里、蛋白质、碳水化合物、脂肪和纤维总量
• 微量营养素 — 详细的维生素／矿物质明细及周期平均值
• 日记管理 — 添加／移除食物记录、复制整天的记录、将日期标记为已完成
• 重复食物 — 创建、列出和删除在选定日期自动记录的重复项目
• 宏量营养素目标 — 读取／写入每日目标、创建模板、设置每周计划
• 禁食 — 查看历史记录和统计数据，取消或删除禁食记录
• 生物特征数据 — 记录和移除体重、血糖、心率、体脂数据
• 原始 CSV 导出 — 摄入量、每日汇总、锻炼、生物特征数据或备注
• 同步到磁盘 — 下载 JSON 导出文件并生成 Markdown 食物记录

快速开始

1. 安装

pip install cronometer-mcp

或从源代码安装：

git clone https://github.com/cphoskins/cronometer-mcp.git
cd cronometer-mcp
pip install -e .

2. 设置凭据

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

或者将它们添加到项目根目录下的 .env 文件中（如果你的 MCP 客户端支持）。

3. 配置 MCP 客户端

Claude Code（.mcp.json）

{
  "mcpServers": {
    "cronometer": {
      "command": "cronometer-mcp",
      "env": {
        "CRONOMETER_USERNAME": "[email protected]",
        "CRONOMETER_PASSWORD": "your-password"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "cronometer": {
      "command": "cronometer-mcp",
      "env": {
        "CRONOMETER_USERNAME": "[email protected]",
        "CRONOMETER_PASSWORD": "your-password"
      }
    }
  }
}

如果你通过 pip install -e . 从源代码安装，也可以使用完整的 Python 路径：

{
  "command": "/path/to/venv/bin/python",
  "args": ["-m", "cronometer_mcp.server"]
}

只读模式

在服务的 env 中设置 CRONOMETER_READ_ONLY=1（也接受 true 或 yes），即可仅公开读取工具。13 个会更改 Cronometer 账户的工具都不会注册，因此客户端完全看不到它们：添加或移除食物记录、宏量营养素目标、计划和模板、禁食记录、生物特征数据、复制日期、将日期标记为已完成，以及重复项目。sync_cronometer 仍可用；它只会在你的设备上写入文件。

此设置限制的是服务提供的功能，而非凭据本身的权限。Cronometer 不提供只读登录，因此 env 中的密码仍可完全访问账户。

远程访问（streamable HTTP）

默认情况下，服务通过 stdio 与客户端通信。要在另一台机器或容器中运行，请设置 CRONOMETER_TRANSPORT=streamable-http，它会改为在 http://<host>:<port>/mcp 提供 MCP 端点。

变量	默认值	含义
CRONOMETER_TRANSPORT	stdio	stdio 或 streamable-http
CRONOMETER_HOST	127.0.0.1	要绑定的接口。在容器内使用 0.0.0.0。
CRONOMETER_PORT	8000	TCP 端口，范围为 1 到 65535
CRONOMETER_ALLOWED_HOSTS	未设置	允许客户端使用的逗号分隔 Host 标头值，格式为 host:port 或 host:*。绑定主机不是回环地址时，请设置此项。

在 Docker 中，使用已发布的软件包时，可通过网络中的 your-server 访问：

docker run --rm -p 8000:8000 \
  -e [email protected] \
  -e CRONOMETER_PASSWORD=your-password \
  -e CRONOMETER_TRANSPORT=streamable-http \
  -e CRONOMETER_HOST=0.0.0.0 \
  -e CRONOMETER_ALLOWED_HOSTS=your-server:8000 \
  python:3.12-slim sh -c "pip install -q cronometer-mcp && cronometer-mcp"

CRONOMETER_ALLOWED_HOSTS 很重要：MCP SDK 仅在绑定到回环地址时才会自行检查 Host 和 Origin 标头。绑定到其他地址时，它会接受所有 Host，这会让你恰好在同一网络上打开的网页通过 DNS 重绑定访问服务。设置允许列表后，Host 或 Origin 不在列表中的请求会收到 421 或 403。如果未设置，服务会在启动时记录警告，但仍会运行。

然后将客户端指向该 URL。Claude Code（.mcp.json）：

{
  "mcpServers": {
    "cronometer": {
      "type": "http",
      "url": "http://your-server:8000/mcp"
    }
  }
}

此端点没有身份验证。任何能够访问该端口的人都可以读取和更改服务持有凭据的 Cronometer 账户。请将其绑定到 127.0.0.1，或将其置于只有你能访问的网络中（VPN 或 Tailscale 可以阻止陌生人，但无法防止上文所述的 DNS 重绑定情况，因此也要设置允许列表），或将其置于需要身份验证的反向代理之后。添加 CRONOMETER_READ_ONLY=1 可以限制远程客户端的操作，但同样需要注意上述情况：凭据本身仍拥有完整访问权限。

可用工具

食物日志与营养

工具	描述
get_food_log	获取日期范围内的单项食物记录，包括宏量营养素和微量营养素
get_daily_nutrition	获取每日宏量营养素总量（卡路里、蛋白质、碳水化合物、脂肪、纤维）
get_micronutrients	获取详细的维生素／矿物质分解数据及期间平均值
export_raw_csv	导出任意数据类型的原始 CSV（份量、运动、生物特征等）

食物搜索与日记管理

工具	描述
search_foods	搜索 Cronometer 食物数据库
list_diary_groups	列出此账户的日记分组，以及 diary_group 接受的值
get_food_details	获取食物的完整营养信息和份量单位 ID
add_food_entry	在日记中添加食物记录
remove_food_entry	从日记中删除食物记录
copy_day	将某一天的所有日记记录复制到另一天
set_day_complete	将某天的日记标记为已完成或未完成

重复食物（重复项目）

工具	描述
get_repeated_items	列出所有重复食物记录
add_repeat_item	添加一条重复食物记录，使其在选定日期自动记入日志
delete_repeat_item	删除一条重复食物记录

宏量营养素目标与模板

工具	描述
get_macro_targets	获取每日宏量营养素目标（或使用 target_date="all" 获取完整的每周计划）
set_macro_targets	更新每日宏量营养素目标（支持部分更新）
list_macro_templates	列出所有已保存的宏量营养素目标模板
create_macro_template	创建新的已保存宏量营养素目标模板
set_weekly_macro_schedule	将模板分配给一周中的各天，作为重复使用的默认设置

断食

工具	描述
get_fasting_history	查看所有断食记录或指定日期范围内的断食记录
get_fasting_stats	汇总断食统计数据（总时长、最长时长、平均值）
cancel_active_fast	取消正在进行的断食，同时保留重复计划
delete_fast	删除一条断食记录

生物特征

工具	描述
get_recent_biometrics	获取最近记录的生物特征条目
add_biometric	记录体重（lbs）、血糖（mg/dL）、心率（bpm）或体脂率（%）
remove_biometric	移除生物特征条目

同步

工具	描述
sync_cronometer	下载 JSON 导出文件并在磁盘上生成 food-log.md

工具参数

所有日期参数均使用 YYYY-MM-DD 格式。省略日期时，大多数工具默认使用今天或最近 7 天。

关键参数模式：

• diary_group — 日记分组的名称（不区分大小写）或从 0 开始的索引。 Cronometer Gold 为每个账户提供 8 个日记分组槽位，你可以自由重命名并启用这些槽位，因此名称因账户而异，不一定是早餐/午餐/晚餐/零食。调用 list_diary_groups 查看你的分组。在未修改过的账户中，四种标准餐点的索引为 1–4（索引 0 是默认禁用的槽位）。未知名称、已禁用的分组和超出范围的索引都会被拒绝，而不会静默使用默认值 — Cronometer 本身会接受错误的索引，但该条目将无法访问。
• days_of_week — "all"、"weekdays"、"weekends" 或以逗号分隔的星期数字（0=周日，6=周六）
• measure_id — 传入 0 以使用通用的克制量（适用于所有食物来源）
• target_date — 在 get_macro_targets 中传入 "all" 以获取完整的每周计划

同步输出

默认情况下，sync_cronometer 工具会将文件保存到 ~/.local/share/cronometer-mcp/。使用 CRONOMETER_DATA_DIR 环境变量覆盖此路径：

export CRONOMETER_DATA_DIR="/path/to/your/project/data/cronometer"

输出文件：

• exports/servings_{start}_{end}.json
• exports/daily_summary_{start}_{end}.json
• exports/servings_latest.json
• exports/daily_summary_latest.json
• food-log.md

工作原理

Cronometer 没有面向个人用户的公共 API。此服务使用与 Cronometer 网页应用内部相同的 GWT-RPC（Google Web Toolkit 远程过程调用）协议：

1. 获取登录页面以取得 anti-CSRF 令牌
2. POST 凭据进行身份验证
3. 调用 GWT-RPC authenticate 获取用户 ID
4. 调用 GWT-RPC generateAuthorizationToken 获取短期导出令牌
5. 使用令牌下载 CSV 导出文件
6. 直接调用 GWT-RPC 方法来编辑日记、管理禁食、生物特征、宏量营养素目标和重复条目

会话 Cookie 会持久保存到 ~/.local/share/cronometer-mcp/.session_cookies，以便后续调用复用会话，而无需重新进行身份验证（Cronometer 对登录频率限制严格）。

GWT 魔法值

GWT 协议使用的排列哈希和标头值会随每次 Cronometer 网页部署而变化。这些值在客户端中硬编码，Cronometer 发布新构建版本时可能会失效。

当前值（截至 2026 年 2 月）：

• 排列：7B121DC5483BF272B1BC1916DA9FA963
• 标头：2D6A926E3729946302DC68073CB0D550

如果身份验证开始出现 GWT 错误，则很可能需要更新这些值。你可以通过以下方式找到当前值：

1. 在浏览器中打开 Cronometer
2. 前往开发者工具 → Network 选项卡
3. 查找发往 cronometer.com/cronometer/app 的请求
4. 检查 x-gwt-permutation 标头和负载结构

你可以通过 CronometerClient 构造函数覆盖这些值：

from cronometer_mcp import CronometerClient

client = CronometerClient(
    gwt_permutation="NEW_PERMUTATION_HASH",
    gwt_header="NEW_HEADER_VALUE",
)

Python API

你也可以直接在 Python 中使用客户端：

from datetime import date, timedelta
from cronometer_mcp import CronometerClient

client = CronometerClient()  # reads from env vars

# Get today's food log
foods = client.get_food_log()

# Get last 7 days of daily summaries
start = date.today() - timedelta(days=7)
summaries = client.get_daily_summary(start)

# Raw CSV export
csv_text = client.export_raw("exercises", start, date.today())

# Copy a day's diary entries
client.copy_day(date(2026, 3, 1), date(2026, 3, 8))

# Add a recurring food entry (every weekday)
client.add_repeat_item(
    food_source_id=12345,
    measure_id=0,        # universal gram-based measure
    quantity=200,
    food_name="Oatmeal",
    diary_group=1,       # 0-based wire index; 1 == Breakfast on a default account
    days_of_week=[1, 2, 3, 4, 5],
)

# Diary groups are user-configured - check what this account actually has
for g in client.diary_groups:
    print(g["wire_index"], g["name"], g["enabled"])

# Log a biometric
client.add_biometric("weight", 218.5, date.today())

许可证

MIT