哈克贝利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 （布尔值，可选）：婴儿是否有尿布疹，默认值：false
notes （字符串，可选）：关于换尿布的可选注意事项
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许可证-有关详细信息，请参阅许可证文件

致谢

与模型上下文协议
使用蓝莓原料药 Python 库
由Anthropic的Claude提供技术支持

迁移历史

v0.2.0-快速MCP迁移（2026-01-31）

从原始MCP SDK迁移到FastMCP框架：

将server.py从442行减少到47行
消除了手动模式定义（270+行）
整合的重复时间戳实用程序
保留了延迟身份验证模式
维护所有现有功能

所有现有的工具和功能对最终用户来说都保持不变。

支持

对于以下问题：

此MCP服务器：在此存储库中打开一个问题
Huckleberry API库：参见蓝莓原料药
哈克贝利应用程序：联系哈克贝利支持
克劳德桌面版：参见人类学文献

Py Huckleberry MCP

快速接入

详细介绍

哈克贝利MCP服务器

特性

先决条件

安装

使用紫外线（推荐）

使用pip

建筑

身份验证设置

Claude桌面配置（推荐）

可用工具

儿童管理

list_children

睡眠跟踪

log_sleep

start_sleep

pause_sleep

resume_sleep

complete_sleep

cancel_sleep

get_sleep_history

喂食追踪

log_breastfeeding

start_breastfeeding

pause_feeding

resume_feeding

switch_feeding_side

complete_feeding

cancel_feeding

get_feeding_history

尿布追踪

log_diaper

get_diaper_history

增长跟踪

log_growth

get_latest_growth

get_growth_history

用法示例

发展

项目结构

添加新工具

运行测试

依赖项

实施说明

故障排除

身份验证错误

服务器未出现在Claude桌面中

服务器无法启动

工具不工作

安全考虑

贡献

许可证

致谢

迁移历史

v0.2.0-快速MCP迁移（2026-01-31）

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_children`

`log_sleep`

`start_sleep`

`pause_sleep`

`resume_sleep`

`complete_sleep`

`cancel_sleep`

`get_sleep_history`

`log_breastfeeding`

`start_breastfeeding`

`pause_feeding`

`resume_feeding`

`switch_feeding_side`

`complete_feeding`

`cancel_feeding`

`get_feeding_history`

`log_diaper`

`get_diaper_history`

`log_growth`

`get_latest_growth`

`get_growth_history`