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。

👥 贡献者

感谢所有为该项目做出贡献的人！查看 贡献者列表。