JinDaGe - apple-health-mcp MCP Details

article

README

🚀 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"
      }
    }
  }
}

数据导出

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

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

可用工具

health_schema：获取可用表及其结构的信息。
health_query：直接对健康数据执行 SQL 查询。
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

故障排除

常见问题

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

🤝 贡献

欢迎贡献代码！请确保：

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

📄 许可证

本项目采用 MIT 许可证。

apple-health-mcp