Apple Health

The Apple Health MCP Server allows you to analyze your health metrics using natural language queries or direct SQL commands.

Features

• 🔍 Natural Language Querying – Transform conversational questions into database queries automatically.
• ⚡ High-Performance SQL Execution – Execute direct SQL queries against health data using DuckDB.
• 📊 Automated Health Reports – Generate comprehensive weekly and monthly health summaries.
• 🚀 Efficient Data Loading – Lazy loading system with configurable time windows for optimal performance.
• 💾 Smart Query Caching – Built-in caching system with TTL to reduce redundant query processing.
• 📱 Complete Apple Health Coverage – Supports all Apple Health data types including quantitative metrics, categories, and workout data.

Use Cases

• Personal Health Analytics: Individuals tracking fitness goals can query correlations between sleep patterns, heart rate variability, and workout performance to optimize their health routines.
• Research Data Analysis: Health researchers working with Apple Health datasets can quickly generate statistical summaries and identify trends across different health metrics without writing custom data processing scripts.
• Medical Consultation Preparation: Patients can create comprehensive health reports covering specific time periods to share with healthcare providers, including detailed breakdowns of symptoms, medications, and vital signs.
• Fitness Coaching Support: Personal trainers and fitness coaches can analyze client data to identify patterns in activity levels, recovery metrics, and performance indicators to adjust training programs.

How To Use It

1. Add the MCP server to your Claude Desktop configuration file. This file is located at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/path/to/your/health/export"
      }
    }
  }
}

2. Configure the server with these environment variables in your config file:

• HEALTH_DATA_DIR (Required): The full path to the directory where you saved your exported Apple Health CSV files.
• MAX_MEMORY_MB (Optional): Sets the maximum memory the server can use. The default is 1024 MB.
• CACHE_SIZE (Optional): The number of query results to keep in the cache. The default is 100.

3. The MCP server relies on a manual data export from your iPhone.

1. Download the Simple Health Export CSV app from the App Store.
2. Open the app and tap the All button to export your data for a specific time range.
3. Transfer the exported ZIP file to your computer using AirDrop or another method.
4. Unzip the file in a location you can easily reference.
5. Update the HEALTH_DATA_DIR in your MCP configuration to point to this new folder.

4. The MCP server provides three main tools you can call from your MCP client:

1. health_schema: Use this to see all available data tables and their structures.
2. health_query: Execute a direct SQL query on your data.
3. health_report: Generate a comprehensive health report based on your data.

FAQs

Q: Why am I getting a “No data found” error?
A: The most common reason is an incorrect path in the HEALTH_DATA_DIR environment variable. Double-check that the path points directly to the folder containing the unzipped CSV files.

Q: My queries are slow or cause memory errors. What can I do?
A: Try reducing the MAX_MEMORY_MB value in your configuration. Also, make your SQL queries more specific by filtering on a smaller date range to reduce the amount of data being processed at once.

Q: I can’t find the table I want to query. How are table names created?
A: Table names are generated from the CSV filenames and are always in lowercase. For instance, a file named HKQuantityTypeIdentifierHeartRate.csv becomes a table named hkquantitytypeidentifierheartrate. You can use the health_schema tool to get a complete list of all available tables.

Q: Why does the server require a third-party app for data export instead of using Apple’s native export?
A: Apple’s native health data export produces XML files that are complex to parse and process efficiently. The Simple Health Export CSV app transforms this data into standardized CSV format that loads faster and queries more reliably through DuckDB.

Q: Can I query data across multiple time periods or combine different export files?
A: Yes, the server can process multiple CSV files from the same directory and automatically combines them into a unified database. You can export different time ranges and place all CSV files in your designated health data directory for comprehensive analysis.