apple-health-mcp

MCP server that loads your Apple Health export into an in-memory SQLite database and exposes it to LLMs via the Model Context Protocol.

Quick start

uvx apple-health-mcp --input ~/Downloads/export.zip

Or install it permanently:

uv tool install apple-health-mcp
apple-health-mcp --input ~/Downloads/export.zip

Exporting your data from Apple Health

1. Open the Health app on your iPhone
2. Tap your profile picture (top-right)
3. Scroll down and tap Export All Health Data
4. Confirm — this may take a few minutes
5. Save or AirDrop the resulting export.zip to your Mac

Claude Desktop integration

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-health": {
      "command": "uvx",
      "args": [
        "apple-health-mcp",
        "--input",
        "/absolute/path/to/export.zip"
      ]
    }
  }
}

Restart Claude Desktop. The tools will appear in the tools menu.

MCP tools

list_metrics()

Returns every distinct record type and its count.

list_workout_types()

Returns every distinct workout activity type and its count.

summary(metric, period)

Aggregates a metric by day, week, or month. Returns count, avg, min, max, and sum.

summary("StepCount", "week")
summary("HeartRate", "month")

query(sql)

Run arbitrary read-only SQL against the database. Only SELECT statements are allowed.

Schema:

records(type, source_name, unit, value, start_date, end_date)
workouts(activity_type, source_name, duration, duration_unit,
         total_energy_kcal, total_distance, distance_unit, start_date, end_date)

Examples:

-- Daily step totals for the last 30 days
SELECT substr(start_date, 1, 10) AS day, sum(CAST(value AS REAL)) AS steps
FROM records WHERE type = 'StepCount'
GROUP BY day ORDER BY day DESC LIMIT 30;

-- Longest runs
SELECT start_date, duration, total_distance, distance_unit
FROM workouts WHERE activity_type = 'Running'
ORDER BY total_distance DESC LIMIT 10;

Environment variable

Instead of --input, you can set:

export HEALTH_EXPORT_PATH=~/Downloads/export.zip

Development

git clone https://github.com/smarzola/apple-health-mcp
cd apple-health-mcp
uv sync                         # install deps + dev tools
uv run pytest                   # run tests
uv run apple-health-mcp --input ~/Downloads/export.zip

Lint, format & typecheck

uv run ruff check src/ tests/          # lint
uv run ruff format --check src/ tests/ # format check
uv run mypy src/                       # typecheck

Auto-fix:

uv run ruff check --fix src/ tests/    # auto-fix lint
uv run ruff format src/ tests/         # auto-format

Pre-commit hooks

uv run pre-commit install     # one-time setup
# Now ruff + mypy run automatically on every commit

Cutting a release

gh release create v0.2.0 --generate-notes
# Triggers GitHub Actions → builds → publishes to PyPI → smoke tests

License

MIT