Apple Health MCP: Query Your Apple Health Data with Natural Language and SQL

Introduction

The apple-health-mcp project by neiltron is an innovative MCP (Model Context Protocol) server that empowers users to interact with their Apple Health data in powerful new ways. Built with TypeScript and leveraging DuckDB for efficient data processing, this server allows you to query your health metrics using either natural language commands or direct SQL queries.

It's important to note that apple-health-mcp currently relies on the Simple Health Export CSV app for exporting your Apple Health data into a usable CSV format. This approach ensures quick and reliable data import for analysis.

Installation

One of the great advantages of apple-health-mcp is that no direct installation is required. You can use it directly with npx via compatible MCP clients, such as Claude Desktop.

To integrate apple-health-mcp with Claude Desktop, add the following configuration to your ~/Library/Application Support/Claude/claude_desktop_config.json file:

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

Environment Variables

Configure the server's behavior using these environment variables:

• HEALTH_DATA_DIR (required): Specifies the path to your Apple Health CSV export directory.
• MAX_MEMORY_MB (optional): Sets the maximum memory usage in MB (default: 1024).
• CACHE_SIZE (optional): Determines the number of cached query results (default: 100).

Examples

Here's an example of a complete configuration for Claude Desktop:

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/Users/yourname/Downloads/HealthAll_2025-07-202_01-04-39_SimpleHealthExportCSV",
        "MAX_MEMORY_MB": "2048"
      }
    }
  }
}

Exporting Data

To get your Apple Health data ready for apple-health-mcp:

1. Download the Simple Health Export CSV app for iOS.
2. In the app, tap the All button to download all data for your desired time range.
3. Transfer the exported ZIP file to your computer (e.g., via AirDrop).
4. Unzip the file to your chosen location.
5. Set the HEALTH_DATA_DIR environment variable in your MCP configuration to this location.

Available Tools

Once configured, you can utilize these tools through your MCP client:

1. health_schema: Get information about available tables and their structure.
2. health_query: Execute SQL queries directly on your health data.
3. health_report: Generate comprehensive health reports.

Why Use It

apple-health-mcp offers several compelling reasons to integrate it into your health data analysis workflow:

• Natural Language Querying: Ask questions about your health data in plain English, and let the MCP client translate them into database queries.
• SQL Query Execution: For advanced users, directly execute SQL queries against your Apple Health data for precise analysis.
• Automated Reports: Generate weekly or monthly health summaries effortlessly, helping you track trends over time.
• Efficient Data Loading: Benefit from lazy loading with configurable time windows, optimizing performance for large datasets.
• Smart Caching: Query results are cached with a configurable TTL (Time To Live), ensuring faster access to frequently requested data.

This project transforms raw Apple Health data into actionable insights, making personal health analysis more accessible and powerful.

Links

• GitHub Repository: neiltron/apple-health-mcp
• Simple Health Export CSV App: Simple Health Export CSV