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

health_schema: Get information about available tables and their structure
health_query: Execute SQL queries directly on your health data
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

"No data found": Check that your CSV files are in the correct directory
Memory errors: Reduce MAX_MEMORY_MB or use shorter time windows
Slow queries: Ensure you're filtering by date ranges
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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

An MCP server that allows users to query and analyze their Apple Health data using SQL and natural language, utilizing DuckDB for fast and efficient health data analysis.

Related MCP Servers

mcp-server-duckdb
ktanaka101
-
security
A
license
-
quality
A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools. It would be interesting to have LLM analyze it. DuckDB is suitable for local analysis.
Last updated -
5
141
Python
MIT License
Duck Duck MCP
qwang07
A
security
A
license
A
quality
This MCP server utilizes DuckDuckGo for web searches, providing structured search results with metadata and features like smart content classification and language detection, facilitating easy integration with AI clients supporting the MCP protocol.
Last updated -
1
418
2
JavaScript
MIT License
mcp-server-motherduckofficial
motherduckdb
-
security
A
license
-
quality
An MCP server for MotherDuck and local DuckDB.
Last updated -
3
266
Python
MIT License
apple-books-mcp
vgnshiyer
-
security
A
license
-
quality
The Apple Books MCP server bridges the gap between your personal reading journey and AI capabilities by transforming static book collections into interactive knowledge repositories.
Last updated -
24
Python
Apache 2.0

View all related MCP servers

Apple Health MCP Server