# 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](https://modelcontextprotocol.io/).

## Quick start

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

Or install it permanently:

```bash
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`):

```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:**

```sql
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:**

```sql
-- 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:

```bash
export HEALTH_EXPORT_PATH=~/Downloads/export.zip
```

## Development

```bash
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

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

Auto-fix:

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

### Pre-commit hooks

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

### Cutting a release

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

## License

MIT