Apple Health MCP Server

🚀 Apple Health MCP Server

Apple Health MCP Server は、LLMベースのエージェントとApple Healthデータをシームレスにやり取りするためのModel Context Protocol (MCP) サーバーを実装しています。XMLエクスポートからインポートされ、ElasticsearchにインデックスされたApple Healthレコードを、包括的なツールセットを通じて照会、分析、管理するための標準化されたインターフェースを提供します。これらのツールはMCP互換クライアント（Claude Desktopなど）からアクセス可能で、ユーザーは自然言語のプロンプトと高度なフィルタリングを使用して、基礎となるデータ形式やElasticsearchクエリを直接知る必要なく、個人の健康データを探索、検索、分析することができます。

🚀 クイックスタート

Apple Health MCP Serverをあなたの環境にセットアップするには、以下の手順に従ってください。

前提条件

• 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ファイルとしてエクスポートし、ファイルシステム内の任意の場所に配置します。デフォルトでは、サーバーはプロジェクトのルートディレクトリにファイルがあることを期待しています。

• 動作例が必要な場合は、このデータセットをお勧めします：https://drive.google.com/file/d/1bWiWmlqFkM3MxJZUD2yAsNHlYrHvCmcZ/view?usp=drive_link
  • Rob Mulla. Predict My Sleep Patterns. https://kaggle.com/competitions/kaggle-pog-series-s01e04, 2023. Kaggle.

2. Elasticsearchインスタンスを準備し、XMLファイルからデータを投入します：

• make esを実行してElasticsearchを起動し、XMLデータをインポートします。
• (オプション) Elasticsearchインデックスからすべてのデータを削除するには、次のコマンドを実行します：

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

設定ファイル

MCPサーバーをLLMクライアントで実行するには、2つの方法があります：

• 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フレームワーク：高性能なMCPサーバー機能を提供するFastMCPに基づいて構築されています
• 🍏 Apple Healthデータ管理：Apple Health XMLエクスポートをインポート、解析、分析します
• 🔎 強力な検索とフィルタリング：自然言語と高度なパラメータを使用して健康レコードを照会およびフィルタリングします
• 📦 Elasticsearch統合：健康データを大規模で効率的にインデックス化および検索します
• 🛠️ モジュール式MCPツール：構造分析、レコード検索、タイプベースの抽出などのツールがあります
• 📈 データの要約とトレンド：健康データから統計情報とトレンド分析を生成します
• 🐳 コンテナ対応：簡単なデプロイとスケーリングのためのDockerサポートがあります
• 🔧 設定可能：広範な.envベースの設定オプションがあります

📦 インストール

上述のクイックスタートセクションを参照してください。

💻 使用例

デモ

このデモでは、Claudeがapple-health-mcp-serverを使用してデータに関する質問に回答する方法を示しています。デモの例のプロンプト：

• 私のApple Healthデータの分析を手伝ってほしいです。まずはデータタイプを分析して、利用可能なデータとその量を確認しましょう。
• 先週の私の活動について何か教えてくれますか？ 日々の統計はどうでしたか？
• 6月と7月のランニングワークアウトをまとめてください。何か面白いことが見られますか？

https://github.com/user-attachments/assets/93ddbfb9-6da9-42c1-9872-815abce7e918

📚 ドキュメント

🔍 プロジェクトについて

Apple Health MCP Server は、LLMベースのエージェントとApple Healthデータをシームレスにやり取りするためのModel Context Protocol (MCP) サーバーを実装しています。XMLエクスポートからインポートされ、ElasticsearchにインデックスされたApple Healthレコードを、包括的なツールセットを通じて照会、分析、管理するための標準化されたインターフェースを提供します。

🏗️ アーキテクチャ

Apple Health MCP Serverは、堅牢な健康データ管理とLLM統合のために設計されたモジュール式で拡張可能なアーキテクチャで構築されています：

• MCPツール：Apple Health XML構造分析、レコード検索、タイプベースの抽出、統計/トレンド生成のための専用ツール。各ツールはMCPプロトコルを介して自然言語およびプログラムによるアクセスが可能です。
• XMLインポートと解析：大規模なApple Health XMLエクスポートの効率的なストリーミングと解析を行い、レコード、ワークアウト、メタデータを抽出してさらなる分析を行います。
• Elasticsearchバックエンド：すべての健康レコードがElasticsearchにインデックスされ、大規模なデータセットにわたる高速でスケーラブルな検索、フィルタリング、集計を可能にします。
• サービス層：XMLおよびElasticsearch操作のビジネスロジックは、専用のサービスモジュールにカプセル化されており、関心事の分離と容易な拡張性を確保しています。
• FastMCPフレームワーク：MCPサーバーのインターフェース、ルーティング、ツール登録を提供し、システムをLLMベースのエージェントとMCPクライアント（Claude Desktopなど）と互換性を持たせます。
• 設定とデプロイ：環境ベースの設定とDockerサポートにより、さまざまな環境での簡単なセットアップとデプロイが可能です。

🔧 設定

環境変数

注意：以下のすべての変数は、必須とマークされていない限りオプションです。設定されていない場合、サーバーは表示されているデフォルト値を使用します。RAW_XML_PATHのみが必須で、Apple Health XMLファイルを指す必要があります。

🛠️ MCPツール

Apple Health MCP Serverは、Apple Healthデータを生のXMLレベルとElasticsearchの両方で探索、検索、分析するためのツールセットを提供します：

XMLツール (xml_reader)

Elasticsearchツール (es_reader)

🗺️ ロードマップ

私たちは、Apple Health MCP Serverに新機能を継続的に追加しています。これからの予定は以下の通りです：

• [ ] インポート時の時系列サンプリング：XMLからElasticsearchへのロードプロセス中に直接時系列データをサンプリングして生成する高度な分析ツールを追加します。
• [ ] 最適化されたXMLツール：XML解析とクエリツールのパフォーマンスと効率を向上させます。
• [ ] 拡張されたElasticsearch分析：Elasticsearchツールセットにより高度な分析と集計機能を追加します。
• [ ] 組み込みデータベースツール：ローカル/オフライン分析とストレージのための組み込みデータベースを操作するためのツールを統合します。

ご提案があれば、お気軽にお問い合わせください。または直接貢献していただいても構いません。

👥 貢献者

📄 ライセンス

このプロジェクトはMITライセンスの下で配布されています。詳細についてはMITライセンスを参照してください。