Apple Health Mcp Server

<a name="readme-top"></a>

<div align="center">

<h1>Apple Health MCP Server</h1>
<p><strong>Apple Health Data Management</strong></p>

</div>

📋 Table of Contents

- 🔍 About
- 💡 Demo
- 🚀 Getting Started
- 📝 Usage
- 🔧 Configuration
- 🐳 Docker Setup
- 🛠️ MCP Tools
- 🗺️ Roadmap
- 👥 Contributors
- 📄 License

🔍 About The Project

Apple Health MCP Server implements a Model Context Protocol (MCP) server designed for seamless interaction between LLM-based agents and Apple Health data. It provides a standardized interface for querying, analyzing, and managing Apple Health records—imported from XML exports and indexed in Elasticsearch—through a comprehensive suite of tools. These tools are accessible from MCP-compatible clients (such as Claude Desktop), enabling users to explore, search, and analyze personal health data using natural-language prompts and advanced filtering, all without requiring direct knowledge of the underlying data formats or Elasticsearch queries.

✨ Key Features

- 🚀 FastMCP Framework: Built on FastMCP for high-performance MCP server capabilities
- 🍏 Apple Health Data Management: Import, parse, and analyze Apple Health XML exports
- 🔎 Powerful Search & Filtering: Query and filter health records using natural language and advanced parameters
- 📦 Elasticsearch Integration: Index and search health data efficiently at scale
- 🛠️ Modular MCP Tools: Tools for structure analysis, record search, type-based extraction, and more
- 📈 Data Summaries & Trends: Generate statistics and trend analyses from your health data
- 🐳 Container Ready: Docker support for easy deployment and scaling
- 🔧 Configurable: Extensive ``.env`-based configuration options

This demo shows how Claude uses the apple-health-mcp-server to answer questions about your data. Example prompts from the demo:
- I would like you to help me analyze my Apple Health data. Let's start by analyzing the data types - check what data is available and how much of it there is.
- What can you tell me about my activity in the last week? How did my daily statistics look?
- Please also summarise my running workouts in July and June. Do you see anything interesting?

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

   cd apple-health-mcp-server

   

   cp config/.env.example config/.env

   

1. Export your Apple Health data as an XML file from your iPhone and place it somewhere in your filesystem. By default, the server expects the file in the project root directory.
- if you need working example, we suggest this dataset: 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. Prepare an Elasticsearch instance and populate it from the XML file:
- Run make es to start Elasticsearch and import your XML data.
- (Optional) To clear all data from the Elasticsearch index, run:


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

     

   make build

   

   {

     "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", // optional - volume for reload

           "type=bind,source=<project-path>/app,target=/root_project/app", // optional

           "--mount",

           "type=bind,source=<project-path>/config/.env,target=/root_project/config/.env",

           "-e",

           "ES_HOST=host.docker.internal",

           "mcp-server:latest"

         ]

       }

     }

   }

   

1. Get the path to your uv binary:
- On Windows:


     (Get-Command uv).Path

     

     which uv

     

   {

     "mcpServers": {

       "uv-mcp-server": {

         "command": "uv",

         "args": [

           "run",

           "--frozen",

           "--directory",

           "<project-path>",

           "start"

         ],

         "env": {

           "PATH": "<path-to-uv-bin-folder>"

         }

       }

     }

   }

   

> Note: All variables below are optional unless marked as required. If not set, the server will use the default values shown. Only RAW_XML_PATH is required and must point to your Apple Health XML file.

| Variable | Description | Example Value | Required |
|--------------------|--------------------------------------------|----------------------|----------|
| RAW_XML_PATH | Path to the Apple Health XML file | raw.xml | ✅ |
| ES_HOST | Elasticsearch host | localhost | ❌ |
| ES_PORT | Elasticsearch port | 9200 | ❌ |
| ES_USER | Elasticsearch username | elastic | ❌ |
| ES_PASSWORD | Elasticsearch password | elastic | ❌ |
| ES_INDEX | Elasticsearch index name | apple_health_data | ❌ |
| XML_SAMPLE_SIZE | Number of XML records to sample | 1000 | ❌ |

XML Tools (xml_reader)

| Tool | Description |
|---------------------|-----------------------------------------------------------------------------------------------|
| get_xml_structure | Analyze the structure and metadata of your Apple Health XML export (file size, tags, types). |
| search_xml_content| Search for specific content in the XML file (by attribute value, device, type, etc.). |
| get_xml_by_type | Extract all records of a specific health record type from the XML file. |

Elasticsearch Tools (es_reader)

| Tool | Description |
|-----------------------------|-----------------------------------------------------------------------------------------------------|
| get_health_summary_es | Get a summary of all Apple Health data in Elasticsearch (total count, type breakdown, etc.). |
| search_health_records_es | Flexible search for health records in Elasticsearch with advanced filtering and query options. |
| get_statistics_by_type_es | Get comprehensive statistics (count, min, max, avg, sum) for a specific health record type. |
| get_trend_data_es` | Analyze trends for a health record type over time (daily, weekly, monthly, yearly aggregations). |

All tools are accessible via MCP-compatible clients and can be used with natural language or programmatic queries to explore and analyze your Apple Health data.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

🗺️ Roadmap

We're continuously enhancing Apple Health MCP Server with new capabilities. Here's what's on the horizon:

- [ ] Time Series Sampling During Import: Add advanced analytical tools to sample and generate time series data directly during the XML-to-Elasticsearch loading process.
- [ ] Optimized XML Tools: Improve the performance and efficiency of XML parsing and querying tools.
- [ ] Expanded Elasticsearch Analytics: Add more advanced analytics and aggregation functions to the Elasticsearch toolset.
- [ ] Embedded Database Tools: Integrate tools for working with embedded databases for local/offline analytics and storage.

Have a suggestion? We'd love to hear from you! Contact us or contribute directly.

👥 Contributors

<a href="https://github.com/the-momentum/apple-health-mcp-server/graphs/contributors">

</a>

<p align="right">(<a href="#readme-top">back to top</a>)</p>

📄 License

Distributed under the MIT License. See MIT License for more information.

---

<div align="center">
<p><em>Built with ❤️ by <a href="https://themomentum.ai">Momentum</a> • Transforming healthcare data management with AI</em></p>
</div>