Apple Health MCP Server

🚀 Apple Health MCP Server

Apple Health MCP Server 實現了一個模型上下文協議（MCP）服務器，旨在實現基於大語言模型（LLM）的智能體與 Apple Health 數據之間的無縫交互。它提供了一個標準化接口，用於查詢、分析和管理從 XML 導出文件導入並在 Elasticsearch 中索引的 Apple Health 記錄。通過一套全面的工具，用戶可以使用自然語言提示和高級過濾功能，探索、搜索和分析個人健康數據，而無需直接瞭解底層數據格式或 Elasticsearch 查詢。

🚀 快速開始

前提條件

• Docker（推薦）或 uv + docker：用於依賴管理。 👉 uv 安裝指南
• 克隆倉庫：

git clone https://github.com/the-momentum/apple-health-mcp-server
cd apple-health-mcp-server

• 設置環境變量：

cp config/.env.example config/.env

編輯 config/.env 文件，填入你的憑證和配置。詳見 環境變量。

準備數據

1. 從你的 iPhone 導出 Apple Health 數據為 XML 文件，並將其放置在文件系統的某個位置。默認情況下，服務器期望該文件位於項目根目錄。

• 如果你需要一個可用的示例，我們推薦這個數據集：Predict My Sleep Patterns
  • Rob Mulla. Predict My Sleep Patterns. Kaggle, 2023.

2. 準備一個 Elasticsearch 實例，並從 XML 文件填充數據：

• 運行 make es 啟動 Elasticsearch 並導入你的 XML 數據。
• （可選）要清除 Elasticsearch 索引中的所有數據，請運行：

uv run python scripts/xml2es.py --delete-all

配置文件

你可以通過以下兩種方式在 LLM 客戶端中運行 MCP 服務器：

• Docker（推薦）
• 本地（uv run）

Docker MCP 服務器

1. 構建 Docker 鏡像：

make build

2. 將以下配置添加到你的 LLM 客戶端設置中（將 <project-path> 替換為你的本地倉庫路徑，將 <xml-file-name> 替換為你從 Apple Health 導出的原始數據文件名（不包含 .xml 擴展名））：

{
  "mcpServers": {
    "docker-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--mount",
        "type=bind,source=<project-path>/{xml-file-name}.xml,target=/root_project/raw.xml",
        "--mount", // 可選 - 用於重新加載的卷
        "type=bind,source=<project-path>/app,target=/root_project/app", // 可選
        "--mount",
        "type=bind,source=<project-path>/config/.env,target=/root_project/config/.env",
        "-e",
        "ES_HOST=host.docker.internal",
        "mcp-server:latest"
      ]
    }
  }
}

本地 uv MCP 服務器

1. 獲取 uv 二進制文件的路徑：

• 在 Windows 上：

(Get-Command uv).Path

• 在 MacOS/Linux 上：

which uv

2. 將以下配置添加到你的 LLM 客戶端設置中（根據需要替換 <project-path> 和 <path-to-bin-folder>）：

{
  "mcpServers": {
    "uv-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "<project-path>",
        "start"
      ],
      "env": {
        "PATH": "<path-to-uv-bin-folder>"
      }
    }
  }
}

<path-to-uv-bin-folder> 應該是包含 uv 二進制文件的文件夾（不要在末尾包含 uv 本身）。

3. 重啟 MCP 客戶端

完成上述步驟後，重啟你的 MCP 客戶端以應用更改。在某些情況下，你可能需要使用任務管理器或系統的進程管理器終止所有相關進程，以確保：

• 正確加載更新後的配置
• 正確應用環境變量
• Apple Health MCP 客戶端以正確的設置初始化

✨ 主要特性

• 🚀 FastMCP 框架：基於 FastMCP 構建，具備高性能 MCP 服務器能力。
• 🍏 Apple Health 數據管理：導入、解析和分析 Apple Health XML 導出文件。
• 🔎 強大的搜索和過濾功能：使用自然語言和高級參數查詢和過濾健康記錄。
• 📦 Elasticsearch 集成：高效地對健康數據進行大規模索引和搜索。
• 🛠️ 模塊化 MCP 工具：提供用於結構分析、記錄搜索、類型提取等的工具。
• 📈 數據摘要和趨勢分析：從健康數據中生成統計信息和趨勢分析。
• 🐳 容器化支持：支持 Docker，便於部署和擴展。
• 🔧 可配置：基於 .env 文件提供廣泛的配置選項。

📦 安裝指南

按照 快速開始 部分的步驟進行安裝和配置。

💻 使用示例

基礎用法

以下是一個使用自然語言查詢 Apple Health 數據的示例：

# 假設這是一個 MCP 客戶端與服務器交互的代碼示例
# 保持原始代碼和註釋不變
# 這裡沒有具體代碼示例，實際使用中需要根據 MCP 客戶端的 API 進行調用

高級用法

# 高級場景說明：使用高級過濾和分析功能查詢特定時間段內的健康數據
# 保持原始代碼和註釋不變
# 這裡沒有具體代碼示例，實際使用中需要根據 MCP 客戶端的 API 進行調用

📚 詳細文檔

🔍 關於本項目

Apple Health MCP Server 實現了一個模型上下文協議（MCP）服務器，旨在實現基於大語言模型（LLM）的智能體與 Apple Health 數據之間的無縫交互。它提供了一個標準化接口，用於查詢、分析和管理 Apple Health 記錄—從 XML 導出文件導入並在 Elasticsearch 中索引—通過一套全面的工具。這些工具可從與 MCP 兼容的客戶端（如 Claude Desktop）訪問，使用戶能夠使用自然語言提示和高級過濾功能探索、搜索和分析個人健康數據，而無需直接瞭解底層數據格式或 Elasticsearch 查詢。

🏗️ 架構

Apple Health MCP 服務器採用模塊化、可擴展的架構，專為強大的健康數據管理和 LLM 集成而設計：

• MCP 工具：專門用於 Apple Health XML 結構分析、記錄搜索、類型提取和統計/趨勢生成的工具。每個工具都可通過 MCP 協議進行自然語言和編程訪問。
• XML 導入和解析：高效地流式處理和解析大型 Apple Health XML 導出文件，提取記錄、鍛鍊數據和元數據以進行進一步分析。
• Elasticsearch 後端：所有健康記錄都在 Elasticsearch 中索引，支持對大型數據集進行快速、可擴展的搜索、過濾和聚合。
• 服務層：XML 和 Elasticsearch 操作的業務邏輯封裝在專用服務模塊中，確保關注點分離和易於擴展。
• FastMCP 框架：提供 MCP 服務器接口、路由和工具註冊，使系統與基於 LLM 的智能體和 MCP 客戶端（如 Claude Desktop）兼容。
• 配置和部署：基於環境的配置和 Docker 支持，便於在各種環境中進行設置和部署。

💡 演示

這個演示展示了 Claude 如何使用 apple-health-mcp-server 回答關於你的數據的問題。演示中的示例提示：

• 我希望你幫助我分析我的 Apple Health 數據。讓我們從分析數據類型開始 - 檢查有哪些可用數據以及數據量有多少。
• 你能告訴我我上週的活動情況嗎？我的每日統計數據如何？
• 請總結我在六月和七月的跑步鍛鍊情況。你發現有什麼有趣的地方嗎？

演示鏈接

🔧 配置

環境變量

⚠️ 重要提示

以下所有變量除非標記為必需，否則均為可選。如果未設置，服務器將使用顯示的默認值。只有 RAW_XML_PATH 是必需的，並且必須指向你的 Apple Health XML 文件。

🛠️ MCP 工具

Apple Health MCP 服務器提供了一套工具，用於在原始 XML 級別和 Elasticsearch 中探索、搜索和分析你的 Apple Health 數據：

XML 工具 (xml_reader)

Elasticsearch 工具 (es_reader)

所有工具都可通過與 MCP 兼容的客戶端訪問，並且可以使用自然語言或編程查詢來探索和分析你的 Apple Health 數據。

🗺️ 路線圖

我們正在不斷增強 Apple Health MCP 服務器的功能。以下是未來的計劃：

• [ ] 導入期間的時間序列採樣：添加高級分析工具，在 XML 到 Elasticsearch 的加載過程中直接採樣和生成時間序列數據。
• [ ] 優化 XML 工具：提高 XML 解析和查詢工具的性能和效率。
• [ ] 擴展 Elasticsearch 分析功能：為 Elasticsearch 工具集添加更多高級分析和聚合功能。
• [ ] 嵌入式數據庫工具集成：集成用於嵌入式數據庫的工具，用於本地/離線分析和存儲。

如果你有建議，歡迎與我們聯繫或直接貢獻代碼。

🔧 技術細節

架構設計

Apple Health MCP 服務器採用模塊化、可擴展的架構，旨在實現高效的健康數據管理和與 LLM 的集成。主要組件包括：

• MCP 工具：提供一系列專門用於處理 Apple Health 數據的工具，如 XML 結構分析、記錄搜索和類型提取。這些工具通過 MCP 協議提供自然語言和編程訪問接口。
• XML 導入和解析：採用流式處理和解析技術，能夠高效處理大型 Apple Health XML 導出文件。它提取記錄、鍛鍊數據和元數據，為後續分析做準備。
• Elasticsearch 後端：所有健康記錄都被索引到 Elasticsearch 中，利用其強大的搜索和聚合功能，實現對大規模數據的快速查詢和分析。
• 服務層：封裝了 XML 和 Elasticsearch 操作的業務邏輯，確保各個組件之間的關注點分離，便於維護和擴展。
• FastMCP 框架：作為 MCP 服務器的核心，提供了接口、路由和工具註冊功能，使系統能夠與基於 LLM 的智能體和 MCP 客戶端無縫交互。
• 配置和部署：基於環境變量的配置方式，結合 Docker 容器化技術，方便在不同環境中進行部署和管理。

性能優化

為了實現高性能的數據處理和查詢，服務器採用了以下技術：

• FastMCP 框架：提供高效的 MCP 服務器實現，確保快速響應和處理請求。
• Elasticsearch 集成：利用 Elasticsearch 的分佈式架構和索引技術，實現大規模數據的快速搜索和聚合。
• 流式處理：在 XML 導入過程中採用流式處理技術，減少內存佔用，提高處理效率。

數據安全

服務器在數據處理和存儲過程中注重數據安全，採取了以下措施：

• 數據加密：在傳輸和存儲過程中對敏感數據進行加密處理，確保數據的機密性。
• 訪問控制：通過配置環境變量和身份驗證機制，限制對服務器和數據的訪問權限。
• 合規性：遵循相關的數據保護法規和標準，確保數據處理過程的合規性。

📄 許可證

本項目採用 MIT 許可證進行分發。詳情請見 MIT License。

👥 貢獻者

感謝所有為該項目做出貢獻的人！查看 貢獻者列表。