Apple Health MCP

🚀 Apple Health MCP 服务器

Apple Health MCP 服务器可让你使用 SQL 查询 Apple Health 数据。它基于 DuckDB 构建，能快速、高效地分析健康数据，为你的健康数据管理提供强大支持。

🚀 快速开始

无需安装！可通过 Claude Desktop 或其他 MCP 客户端直接使用 npx 来调用。

✨ 主要特性

• 自然语言查询：MCP 客户端可将你的问题转化为数据库查询。
• SQL 查询执行：可直接针对 Apple Health 数据执行 SQL 查询。
• 自动报告：能生成每周/每月健康摘要。
• 高效数据加载：支持使用可配置的时间窗口进行懒加载。
• 智能缓存：查询结果可进行 TTL 缓存。

📦 安装指南

无需安装！可通过 Claude Desktop 或其他 MCP 客户端直接使用 npx 调用。

💻 使用示例

使用 Claude Desktop

将以下内容添加到你的 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/path/to/your/health/export"
      }
    }
  }
}

环境变量

• HEALTH_DATA_DIR（必需）：Apple Health CSV 导出目录的路径。
• MAX_MEMORY_MB（可选）：最大内存使用量（MB），默认值为 1024。
• CACHE_SIZE（可选）：缓存的查询结果数量，默认值为 100。

示例配置

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/Users/yourname/Downloads/HealthAll_2025-07-202_01-04-39_SimpleHealthExportCSV",
        "MAX_MEMORY_MB": "2048"
      }
    }
  }
}

数据导出

若要获取数据，请按以下步骤操作：

1. 为你的 iOS 设备下载 Simple Health Export CSV 应用。
2. 在应用中点击 All 按钮，下载你所需时间范围（默认为 1 个月）的所有数据。
3. 当系统提示时，通过隔空投送或其他方式将数据传输到你的电脑。
4. 将文件解压到你指定的位置。
5. 在你的 MCP 配置中设置 HEALTH_DATA_DIR 的值，具体可参考示例配置。

可用工具

1. health_schema：获取可用表及其结构的信息。
2. health_query：直接对健康数据执行 SQL 查询。
3. health_report：生成全面的健康报告。

数据结构

服务器期望 Apple Health 数据以 CSV 文件形式导出，且文件名需遵循以下模式：

• HKQuantityTypeIdentifier*.csv：定量健康指标。
• HKCategoryTypeIdentifier*.csv：分类健康数据。
• HKWorkoutActivityType*.csv：锻炼和活动数据。

每个 CSV 文件应包含以下列：

• type：具体的健康指标类型。
• sourceName：源设备/应用。
• startDate：开始时间戳（UTC）。
• endDate：结束时间戳（UTC）。
• value：测量值。
• unit：测量单位。

开发

若要进行本地开发，请按以下步骤操作：

# 克隆项目并安装依赖
git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
npm install

# 构建项目
npm run build

# 类型检查
npm run typecheck

故障排除

常见问题

1. “未找到数据”：检查你的 CSV 文件是否位于正确的目录中。
2. 内存错误：减小 MAX_MEMORY_MB 的值或使用更短的时间窗口。
3. 查询缓慢：确保你按日期范围进行过滤。
4. 表缺失：表名是小写的（例如，hkquantitytypeidentifierheartrate）。

🤝 贡献

欢迎贡献代码！请确保：

• 代码遵循现有模式。
• 正确定义 TypeScript 类型。
• 具备全面的错误处理。
• 考虑对性能的影响。

📄 许可证

本项目采用 MIT 许可证。