neiltron/apple-health-mcp: MCP server for querying Apple Health data with natural language and SQL

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

• 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

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

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"
      }
    }
  }
}

• 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)

{
  "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"
      }
    }
  }
}

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.

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

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

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

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)

Contributions are welcome! Please ensure:

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

MIT

Keep your files stored safely and securely with the SanDisk 2TB Extreme Portable SSD. With over 69,505 ratings and an impressive 4.6 out of 5 stars, this product has been purchased over 8K+ times in the past month. At only $129.99, this Amazon’s Choice product is a must-have for secure file storage.

Help keep private content private with the included password protection featuring 256-bit AES hardware encryption. Order now for just $129.99 on Amazon!

Help Power Techcratic’s Future – Scan To Support

If Techcratic’s content and insights have helped you, consider giving back by supporting the platform with crypto. Every contribution makes a difference, whether it’s for high-quality content, server maintenance, or future updates. Techcratic is constantly evolving, and your support helps drive that progress.

As a solo operator who wears all the hats, creating content, managing the tech, and running the site, your support allows me to stay focused on delivering valuable resources. Your support keeps everything running smoothly and enables me to continue creating the content you love. I’m deeply grateful for your support, it truly means the world to me! Thank you!