哈克贝利MCP服务器
免责声明：这是一个非官方的社区建设项目。它不是由哈克贝利赞助、认可或支持的。使用风险自负。
使用FastMCP构建的模型上下文协议（MCP）服务器与Huckleberry婴儿跟踪API接口，使Claude能够通过自然对话帮助您跟踪婴儿的睡眠、喂养、尿布更换和生长测量。
特性
- 儿童管理：列出并管理多个子配置文件
- 睡眠跟踪：通过自动历史跟踪启动、暂停、恢复、完成和取消睡眠会话
- 喂食追踪：通过侧边切换跟踪母乳喂养过程
- 尿布记录：记录尿布更换的类型、数量、颜色和一致性细节
- 增长跟踪：记录并检索体重、身高和头围测量值
先决条件
- Python 3.10或更高版本
- 持有有效凭证的哈克贝利账户
- Claude桌面应用程序（用于集成）
uv包管理器（推荐）或pip
安装
使用紫外线（推荐）
# Clone or navigate to the project directory
cd /path/to/huckleberry-mcp
uv sync使用pip
cd /path/to/huckleberry-mcp
pip install -e .建筑
此服务器使用 快速MCP MCP服务器快速开发框架。FastMCP提供：
- 通过装饰器自动注册工具
- 从类型提示和文档字符串生成模式
- 内置错误处理和协议合规性
- 支持多种传输类型（STDIO、HTTP）
该服务器在5个类别中实现了22个工具：
- 儿童管理（2个工具）
- 睡眠跟踪（7个工具）
- 喂食跟踪（8个工具）
- 尿布追踪（2个工具）
- 增长跟踪（3个工具）
所有工具都使用延迟身份验证——凭据在首次使用工具时进行验证，而不是在服务器启动时进行验证。
身份验证设置
服务器要求将您的Huckleberry凭据配置为环境变量。
Claude桌面配置（推荐）
使用您的凭据将服务器添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"huckleberry": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/huckleberry-mcp",
"run",
"huckleberry-mcp"
],
"env": {
"HUCKLEBERRY_EMAIL": "your-email@example.com",
"HUCKLEBERRY_PASSWORD": "your-password",
"HUCKLEBERRY_TIMEZONE": "America/New_York"
}
}
}
}重要:
- 替换
/absolute/path/to/huckleberry-mcp该项目的实际绝对路径 - 在macOS上，如果使用Anaconda，请指定以下内容的完整路径
uv:/Users/your-username/anaconda3/bin/uv - 确保
uv位于您的PATH中，或使用指向的完整路径uv可执行
可用工具
儿童管理
list_children
列出所有孩子的UID、姓名和出生日期。
示例：“列出我的孩子”
睡眠跟踪
log_sleep
直接记录已完成的睡眠会话，而无需使用计时器。可用于追溯记录或导入过去的睡眠数据。
参数:
child_uid（string，必填）：孩子的唯一标识符start_time（字符串，必填）：ISO格式的睡眠开始时间。如果没有指定时区（例如，“2026-01-30T14:30:00”），则解释为您配置的时区。对于UTC，使用“2026-01-30T14:30:00Z”。end_time（字符串，可选）：ISO格式的睡眠结束时间（提供此OR duration_minutes）。时区处理与start_time相同。duration_minutes（整数，可选）：睡眠持续时间（分钟）（提供此OR end_time）
时区注释：没有时区信息的时间将使用您的 HUCKLEBERRY_TIMEZONE 设置（例如“美国/纽约”）。这确保了哈克贝利应用程序中的时间显示正确。
示例：“记录昨天下午2点到4点的睡眠会话”
start_sleep
使用实时计时器为孩子开始睡眠跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“为Alice启动睡眠会话”
pause_sleep
暂停活动的睡眠跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“暂停睡眠会话”
resume_sleep
恢复暂停的睡眠跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“恢复睡眠会话”
complete_sleep
完成并保存睡眠跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“完成睡眠会话”
cancel_sleep
取消并放弃睡眠跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“取消睡眠会话”
get_sleep_history
获取某个日期范围内儿童的睡眠历史记录（默认为过去7天）。
参数:
child_uid（string，必填）：孩子的唯一标识符start_date（字符串，可选）：ISO格式的开始日期（YYYY-MM-DD），包括在内end_date（字符串，可选）：ISO格式的结束日期（YYYY-MM-DD），不包括此日期的数据
重要：The end_date 是独家的。要获取一天（例如1月30日）的数据，请设置 start_date='2026-01-30' 和 end_date='2026-01-31'.
示例：“显示上周的睡眠历史记录”
喂食追踪
log_breastfeeding
直接记录已完成的母乳喂养过程，无需使用计时器。可用于追溯记录或导入过去的喂食数据。
参数:
child_uid（string，必填）：孩子的唯一标识符start_time（字符串，必填）：ISO格式的进料开始时间。如果没有指定时区，则解释为您配置的时区。left_duration_minutes（整数，可选）：左胸持续时间（分钟）right_duration_minutes（整数，可选）：右胸持续时间（分钟）end_time（字符串，可选）：ISO格式的进料结束时间（提供此OR持续时间）last_side（字符串，可选）：哪一侧完成（“左”或“右”）。如果使用end_time，则为必填项。
使用模式:
- 持续时间：提供
left_duration_minutes和right_duration_minutes - 结束时间：提供
end_time和last_side（自动计算持续时间）
时区注释：没有时区信息的时间将使用您的 HUCKLEBERRY_TIMEZONE 设置。
例子:
- “在左侧记录昨天下午2点至2点30分的母乳喂养时间”
- “记录母乳喂养：从今天下午3点开始，还剩10分钟，右边15分钟”
start_breastfeeding
使用实时计时器开始母乳喂养跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符side（string，必填）：从哪一侧开始（“左”或“右”）
示例：“从左侧开始母乳喂养”
pause_feeding
暂停正在进行的喂食跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“暂停喂食”
resume_feeding
恢复暂停的喂食跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“恢复喂食”
switch_feeding_side
母乳喂养时，在左乳房和右乳房之间切换。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“切换到另一侧”
complete_feeding
完成并保存喂食跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“完全喂养”
cancel_feeding
取消并放弃喂食跟踪会话。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“取消喂食”
get_feeding_history
获取某个日期范围内儿童的喂养历史记录（默认为过去7天）。
参数:
child_uid（string，必填）：孩子的唯一标识符start_date（字符串，可选）：ISO格式的开始日期（YYYY-MM-DD），包括在内end_date（字符串，可选）：ISO格式的结束日期（YYYY-MM-DD），不包括此日期的数据
重要：The end_date 是独家的。要获取一天（例如1月30日）的数据，请设置 start_date='2026-01-30' 和 end_date='2026-01-31'.
示例：“给我看看今天的喂食”
尿布追踪
log_diaper
记录尿布更换的详细信息。支持带可选时间戳的追溯日志记录。
参数:
child_uid（string，必填）：孩子的唯一标识符mode（字符串，可选）：尿布模式（“撒尿”、“便便”、“两者”、“干燥”），默认值：“两者”pee_amount（字符串，可选）：小便量（“小”、“中”、“大”）poo_amount（字符串，可选）：Poo数量（“小”、“中”、“大”）color（字符串，可选）：Poo颜色（“黄色”、“棕色”、“黑色”、“绿色”、“红色”、“灰色”）consistency（字符串，可选）：Poo稠度（如果存在）（“固体”、“松散”、“流动”、“粘稠”、“坚硬”、“鹅卵石”、“腹泻”）diaper_rash（布尔值，可选）：婴儿是否有尿布疹，默认值：falsenotes（字符串，可选）：关于换尿布的可选注意事项timestamp（字符串，可选）：ISO格式的时间戳，用于追溯日志记录。如果未提供，则使用当前时间。
时区注释：没有时区信息的时间将使用您的 HUCKLEBERRY_TIMEZONE 设置。
例子:
- “用小便和大便记录尿布更换”
- “记录2小时前的湿尿布”（带追溯时间戳）
get_diaper_history
获取某个日期范围内儿童的尿布更换历史记录（默认为过去7天）。
参数:
child_uid（string，必填）：孩子的唯一标识符start_date（字符串，可选）：ISO格式的开始日期（YYYY-MM-DD），包括在内end_date（字符串，可选）：ISO格式的结束日期（YYYY-MM-DD），不包括此日期的数据
重要：The end_date 是独家的。要获取一天（例如1月30日）的数据，请设置 start_date='2026-01-30' 和 end_date='2026-01-31'.
示例：“给我看看今天换的尿布”
增长跟踪
log_growth
记录生长测量值（体重、身高、头围）。支持带可选时间戳的追溯日志记录。
参数:
child_uid（string，必填）：孩子的唯一标识符weight（数字，可选）：重量（英制单位为磅，公制单位为千克）height（数字，可选）：高度（英制单位为英寸，公制单位为厘米）head（数字，可选）：头围（英制单位为英寸，公制单位为厘米）units（字符串，可选）：测量系统（“英制”或“公制”），默认值：“英制”timestamp（字符串，可选）：ISO格式的时间戳，用于追溯日志记录。如果未提供，则使用当前时间。
时区注释：没有时区信息的时间将使用您的 HUCKLEBERRY_TIMEZONE 设置。
例子:
- “原木重量为12.5磅，高度为24英寸”
- “记录昨天就诊的体重测量值”（带追溯时间戳）
get_latest_growth
获取孩子的最新生长测量数据。
参数:
child_uid（string，必填）：孩子的唯一标识符
示例：“最新的增长指标是什么？”
get_growth_history
获取某个日期范围内儿童的生长测量历史记录（默认为过去30天）。
参数:
child_uid（string，必填）：孩子的唯一标识符start_date（字符串，可选）：ISO格式的开始日期（YYYY-MM-DD），包括在内end_date（字符串，可选）：ISO格式的结束日期（YYYY-MM-DD），不包括此日期的数据
重要：The end_date 是独家的。要获取一天（例如1月30日）的数据，请设置 start_date='2026-01-30' 和 end_date='2026-01-31'.
示例：“显示上个月的增长历史”
用法示例
在Claude Desktop中配置后，您可以通过自然对话与服务器交互：
- 列出你的孩子:
- “列出我的孩子” - “让我看看我所有的孩子”
- 追踪睡眠:
- “记录昨天下午2点至4点的睡眠会话”（直接记录） - “记录爱丽丝从今天下午1点开始睡了90分钟”（直接记录） - “为Alice启动睡眠会话”（实时计时器） - “爱丽丝睡着了” - “暂停睡眠定时器” - “爱丽丝醒了，完成了睡眠过程” - “显示上周的睡眠历史记录”
- 跟踪喂食:
- “在左侧记录下午2点至下午2:30的母乳喂养时间”（直接记录） - “记录母乳喂养：从下午3点开始，左10分钟，右15分钟”（直接记录） - “从左侧开始母乳喂养”（实时计时器） - “换到右胸” - “完成喂食环节” - “给我看看今天的喂食”
- 记录尿布更换:
- “用小便和大便记录尿布更换” - “把尿布弄湿” - “用松散的黄色便便做一块大便尿布” - “换尿布时大便和尿布疹中等”
- 跟踪增长:
- “原木重量为12.5磅” - 原木重量12.5磅，高度24英寸，头部16英寸 - “最新的增长指标是什么？” - “显示上个月的增长历史”
- 查看历史:
- “显示上周的睡眠记录” - “今天换了多少尿布？” - “给我看看昨天的所有喂食”
发展
项目结构
src/huckleberry_mcp/
├── server.py # FastMCP server instance and tool registration
├── auth.py # Authentication handling (lazy singleton pattern)
├── utils.py # Shared utilities (ISO timestamp conversion)
└── tools/ # Tool implementations
├── children.py # Child management tools
├── sleep.py # Sleep tracking tools
├── feeding.py # Feeding/breastfeeding tools
├── diaper.py # Diaper logging tools
└── growth.py # Growth measurement tools添加新工具
要添加新工具，请执行以下操作：
- 将该函数添加到中的相应模块
tools/ - 用…装饰
@mcp.tool() - 添加全面的文档字符串（用于模式生成）
- 使用类型提示进行参数验证
- 注册于
server.py如果创建新模块
例子：
@mcp.tool()
async def my_new_tool(child_uid: str, data: str) -> Dict[str, Any]:
"""Tool description here.
Args:
child_uid: The child's unique identifier
data: Some data parameter
Returns:
Status message and data
"""
api = await get_authenticated_api()
# Implementation...
return {"success": True, "message": "Done"}运行测试
# Run all tests
uv run pytest tests/ -v
# Run specific test file
uv run pytest tests/test_sleep.py -v
# Run with coverage
uv run pytest tests/ --cov=huckleberry_mcp --cov-report=html依赖项
fastmcp>=2.0.0,=0.1.0-Huckleberry API客户端库python-dotenv>=1.0.0-环境变量管理
实施说明
此服务器已完全重构以匹配实际 蓝莓原料药 库界面：
- 所有历史记录方法都在内部使用Unix时间戳，并转换为/转换为ISO日期
- 定时器操作（睡眠/喂食）直接调用API方法，无需状态预先检查
- 增长跟踪用途
head参数而不是head_circumference - 尿布记录包括金额字段(
pee_amount,poo_amount)并使用color而不是poo_color - 即使凭据无效，服务器也会成功启动，在调用工具时返回有用的错误
故障排除
身份验证错误
如果在调用工具时看到身份验证错误：
- 在Claude Desktop配置中验证您的凭据是否正确
- 确保您的哈克贝利帐户处于活动状态，您可以通过应用程序登录
- 检查时区是否有效（例如，“美国/纽约”、“欧洲/伦敦”）
- 服务器将成功启动，但当您调用工具时会进行身份验证
服务器未出现在Claude桌面中
- 验证配置文件路径是否适用于您的操作系统
- 检查一下
--directory路径是绝对正确的 - 在装有Anaconda的macOS上，使用uv的完整路径：
/Users/your-username/anaconda3/bin/uv - 更改配置后重新启动Claude Desktop
- 检查Claude Desktop日志中的错误消息
- 确保
uv已安装且可访问
服务器无法启动
如果您看到“生成进程失败：没有这样的文件或目录”：
- 这
uv找不到命令-指定命令的完整路径uv可执行 - 在macOS上，使用以下命令查找uv：
which uv或检查/Users/your-username/anaconda3/bin/uv - 更新
command配置中的字段使用绝对路径
工具不工作
- 确保您首先列出了孩子，以获得有效的孩子UID
- 使用工具时验证子UID是否正确
- 定时器会话可以在不先检查状态的情况下启动/停止
- 查看特定验证问题的错误消息（无效颜色、数量等）
安全考虑
- 永远不要承诺你的
.env文件或凭据到版本控制 - 仅将凭据存储在环境变量或Claude Desktop配置中
- 这
.gitignore文件排除.env默认情况下的文件 - 服务器从不记录凭据
- 所有API通信都使用HTTPS
贡献
这是一个个人项目，但欢迎提出建议和错误报告！
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
迁移历史
v0.2.0-快速MCP迁移（2026-01-31）
从原始MCP SDK迁移到FastMCP框架：
- 将server.py从442行减少到47行
- 消除了手动模式定义（270+行）
- 整合的重复时间戳实用程序
- 保留了延迟身份验证模式
- 维护所有现有功能
所有现有的工具和功能对最终用户来说都保持不变。
支持
对于以下问题：