Huckleberry MCP Server

面向 Claude、Cursor、VS Code 及其他 AI 助手的非官方 Huckleberry 婴儿追踪器 MCP 服务器。可查询并记录婴儿睡眠、喂养、尿布、吸奶、辅食、如厕和成长记录。

直接在 Claude Desktop 中展示 Huckleberry 的数据（睡眠、喂养、成长、尿布、辅食），或将 MCP 服务器集成到其他 AI 应用中。

安装

环境要求

• Node.js 24+（与 CI 一致；参见 .nvmrc）

• npm 9+

快速开始

npm install -g node-huckleberry-mcp

或直接通过 npx 使用：

npx node-huckleberry-mcp

从源码构建

git clone https://github.com/KenLSM/node-huckleberry-mcp.git
cd node-huckleberry-mcp
npm install
npm run build
node dist/index.js

Related MCP server: whoop-ai-mcp

配置

环境变量

服务器从环境变量中读取凭据：

HUCKLEBERRY_EMAIL=you@example.com
HUCKLEBERRY_PASSWORD=your-password
HUCKLEBERRY_TIMEZONE=America/New_York

在项目根目录创建 .env 文件（模板参见 .env.example）：

cp .env.example .env
# Edit .env with your Huckleberry credentials

注意： 切勿将 .env 提交到版本控制。.gitignore 已将其排除。

Claude Desktop 集成

要在 Claude Desktop 中使用此服务器，请将其添加到你的 claude_desktop_config.json：

macOS/Linux： ~/.config/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huckleberry": {
      "command": "npx",
      "args": ["node-huckleberry-mcp"],
      "env": {
        "HUCKLEBERRY_EMAIL": "you@example.com",
        "HUCKLEBERRY_PASSWORD": "your-password",
        "HUCKLEBERRY_TIMEZONE": "America/New_York"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。Huckleberry 工具将出现在工具列表中。

工具

服务器在 6 个类别中提供 29 个工具。（活动会话的睡眠/喂养计时器——start_sleep、pause_feeding 等——尚未实现；请使用显式的 log_* 工具记录已完成的事件。）

儿童管理（2）

睡眠（4）

喂养（10）

尿布（5）

color 和 consistency 被限制为一组固定值（yellow/brown/green/black/red/white/orange/other；hard/normal/soft/runny/watery/formed/mucousy），以防止无法识别的值导致 Huckleberry 应用在该条目上崩溃。关于该集合的选取方式，参见 TASKS.md → BUG2——该集合继承自旧版移植，尚未经线上确认。

成长（5）

辅食——自定义食物（3）

所有 start/end 输入均为 epoch 秒。时间以从 HUCKLEBERRY_TIMEZONE 推导出的时区 offset 存储。

每个 log_* 工具都接受可选的自由文本 notes 字段，该字段存储在条目上，并由对应的 history/get_* 工具返回（每个读取的条目都包含其 Firestore id）。edit_* 工具（edit_sleep、edit_feed、edit_pump、edit_diaper、edit_growth）更新现有条目上的 notes 及其他字段，delete_* 工具则删除一个条目——两者都从对应的读取操作中获取 id/interval_id/entry_id。删除不会重新计算追踪器的 prefs.last* 摘要，因此“最近”视图可能会短暂显示已删除的条目，直到下一次写入。

提示词

服务器还提供 MCP 提示词（在支持的客户端中以斜杠命令风格的模板呈现）：huckleberry_usage（加载使用约定）、daily_summary（date?）和 log_event（event）。

智能体技能

skills/huckleberry/SKILL.md 教助手如何正确使用这些工具（儿童解析、自然语言时间 → epoch 秒、单位、写入前确认）。将其复制到你的 Claude 技能目录中，可让 MCP 使用起来更顺畅。

开发

脚本

npm run build            # TypeScript → JavaScript (tsc)
npm run lint             # Lint with oxlint
npm run lint:fix         # Lint and auto-fix
npm run format           # Format with oxfmt
npm run format:check     # Check formatting without changes
npm test                 # Run unit tests (Vitest)
npm run test:watch       # Watch mode for tests
npm run test:integration # Live tests (needs HUCKLEBERRY_* creds; skipped otherwise). Read-only by default; set HUCKLEBERRY_ALLOW_WRITES=1 to also run the log_*→delete write round-trip (test account only)
npm run inspect:schema   # Dump real Firestore shapes (needs creds) — see docs/integration-testing.md
npm run smoke            # Build + run the MCP server smoke test
npm run dev              # Run in dev mode (tsx)

工具链

• TypeScript 5.3+，启用严格模式

• oxc（oxlint + oxfmt）——基于 Rust 的快速 lint 与格式化工具

• Vitest——单元测试运行器

• Zod——运行时数据验证

• Firebase JS SDK——Firestore + Auth

架构

src/
├── auth/            # Authentication (T1.1)
├── client/          # Huckleberry API operations (T1.2–T1.9)
├── models/          # Zod schemas for Firestore docs (T1.3)
├── server/          # MCP server framework (T2.1–T2.2)
├── tools/           # MCP tool implementations (T2.3–T2.8)
├── __tests__/       # Unit & smoke tests
└── index.ts         # Entry point

架构细节和约定参见 AGENTS.md。

测试

单元测试位于 src/__tests__/，使用 Vitest 并模拟 Firebase：

npm test

运行单个测试文件：

npm test -- models.test.ts

监视模式：

npm run test:watch

实时集成测试（受门控）针对真实账户进行验证，没有凭据时会被跳过。默认情况下为只读；可选的 log_*→删除写入往返测试仅在设置 HUCKLEBERRY_ALLOW_WRITES=1 时运行（请使用测试账户）——参见 docs/integration-testing.md：

# read-only schema validation
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… npm run test:integration

# also exercise log_*→delete writes (test account only)
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… HUCKLEBERRY_ALLOW_WRITES=1 npm run test:integration

许可与署名

本项目是两个 MIT 许可项目的 Node.js 移植：

• py-huckleberry-api © 2025 Woyken（GitHub，MIT License）

• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors（GitHub，MIT License）

此移植包含来自两个上游项目的大量设计与实现。

安全与隐私

• 本地不存储任何数据。 所有操作都是对你 Huckleberry Firestore 数据库的经过身份验证的读/写。

• 凭据基于环境变量。 切勿提交 .env 或硬编码凭据。

• 这是第三方服务的非官方客户端；API 是逆向工程得出的，可能会发生变化。

支持

• 文档： 贡献者指南参见 AGENTS.md。

• 问题： 请在 GitHub Issues 上报告错误或请求功能。

• 上游： 有关 Huckleberry 数据或 API 变更的问题，请参阅原始 Python 项目。

用 ❤️ 构建，作为 py-huckleberry-api 和 py-huckleberry-mcp 的 Node/TypeScript 移植版。