apple-health-mcp

Apple Health MCP Server

An MCP (Model Context Protocol) server for querying Apple Health data using SQL. Built with DuckDB for fast, efficient health data analysis.

[!NOTE]
This project currently relies on the Simple Health Export CSV app by Eric Wolter. See Exporting Data below for more info on how best to use the app.

This is currently the easiest way I could find to quickly and reliably get Apple Health data exported in CSV format. If you have ideas of better ways to import data, please submit an issue.

Features

• Natural language querying: Your MCP client translates your questions to database queries
• SQL Query Execution: Direct SQL queries against your Apple Health data
• Automated Reports: Generate weekly/monthly health summaries
• Efficient Data Loading: Lazy loading with configurable time windows
• Smart Caching: Query result caching with TTL

Installation

No installation required! Use directly with npx via Claude Desktop or other MCP clients.

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/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"
      }
    }
  }
}

Environment Variables

• HEALTH_DATA_DIR (required): Path to your Apple Health CSV export directory
• MAX_MEMORY_MB (optional): Maximum memory usage in MB (default: 1024)
• CACHE_SIZE (optional): Number of cached query results (default: 100)

Example Configuration

{
  "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 use get your data:

• Download the Simple Health Export CSV app for iOS.
• Tap the All button in the app to download all data for your desired time range (default 1 month).
• When prompted, Airdrop it to your computer or transfer it some other way.
• Unzip the file to your desired location
• Set the HEALTH_DATA_DIR value in your MCP config. See Example Configuration above.

Available Tools

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

Data Structure

The server expects Apple Health data exported as CSV files with the following naming pattern:

• HKQuantityTypeIdentifier*.csv - Quantitative health metrics
• HKCategoryTypeIdentifier*.csv - Categorical health data
• HKWorkoutActivityType*.csv - Workout and activity data

Each CSV file should have these columns:

• type: The specific health metric type
• sourceName: Source device/app
• startDate: Start timestamp (UTC)
• endDate: End timestamp (UTC)
• value: The measurement value
• unit: Unit of measurement

Development

For local development:

# Clone and install dependencies
git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
npm install

# Build the project
npm run build

# Type checking
npm run typecheck

Troubleshooting

Common Issues

1. "No data found": Check that your CSV files are in the correct directory
2. Memory errors: Reduce MAX_MEMORY_MB or use shorter time windows
3. Slow queries: Ensure you're filtering by date ranges
4. Missing tables: Table names are lowercase (e.g., hkquantitytypeidentifierheartrate)

Contributing

Contributions are welcome! Please ensure:

• Code follows existing patterns
• TypeScript types are properly defined
• Error handling is comprehensive
• Performance impact is considered

License

MIT