shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

apple-health-mcp-server

Apple Health MCP Server是一个基于FastMCP框架的模型上下文协议服务器，专为LLM代理与苹果健康数据交互设计。它提供标准化接口，通过Elasticsearch索引和查询健康数据，支持自然语言搜索、分析和统计功能，包含XML和Elasticsearch两大工具集，支持Docker部署。

article

README

🚀 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 文件，并将其放置在文件系统的某个位置。默认情况下，服务器期望该文件位于项目根目录。
  1. 准备一个 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
  1. 将以下配置添加到你的 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
  1. 将以下配置添加到你的 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 文件。

| 属性 | 详情 | |------|------| | 变量名 | 描述 | | RAW_XML_PATH | Apple Health XML 文件的路径 | | ES_HOST | Elasticsearch 主机 | | ES_PORT | Elasticsearch 端口 | | ES_USER | Elasticsearch 用户名 | | ES_PASSWORD | Elasticsearch 密码 | | ES_INDEX | Elasticsearch 索引名称 | | XML_SAMPLE_SIZE | 要采样的 XML 记录数量 |

| 变量 | 描述 | 示例值 | 是否必需 | |------|------|------|------| | RAW_XML_PATH | Apple Health XML 文件的路径 | raw.xml | ✅ | | ES_HOST | Elasticsearch 主机 | localhost | ❌ | | ES_PORT | Elasticsearch 端口 | 9200 | ❌ | | ES_USER | Elasticsearch 用户名 | elastic | ❌ | | ES_PASSWORD | Elasticsearch 密码 | elastic | ❌ | | ES_INDEX | Elasticsearch 索引名称 | apple_health_data | ❌ | | XML_SAMPLE_SIZE | 要采样的 XML 记录数量 | 1000 | ❌ |

🛠️ MCP 工具

Apple Health MCP 服务器提供了一套工具，用于在原始 XML 级别和 Elasticsearch 中探索、搜索和分析你的 Apple Health 数据：

XML 工具 (xml_reader)

| 工具 | 描述 | |------|------| | get_xml_structure | 分析你的 Apple Health XML 导出文件的结构和元数据（文件大小、标签、类型）。 | | search_xml_content | 在 XML 文件中搜索特定内容（按属性值、设备、类型等）。 | | get_xml_by_type | 从 XML 文件中提取特定健康记录类型的所有记录。 |

Elasticsearch 工具 (es_reader)

| 工具 | 描述 | |------|------| | get_health_summary_es | 获取 Elasticsearch 中所有 Apple Health 数据的摘要（总数、类型细分等）。 | | search_health_records_es | 在 Elasticsearch 中灵活搜索健康记录，支持高级过滤和查询选项。 | | get_statistics_by_type_es | 获取特定健康记录类型的综合统计信息（计数、最小值、最大值、平均值、总和）。 | | get_trend_data_es | 分析特定健康记录类型随时间的趋势（每日、每周、每月、每年聚合）。 |

所有工具都可通过与 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。

👥 贡献者

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

由 Momentum 用心打造 • 用人工智能改变医疗数据管理

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端