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 許可證。