Skip to main content
Glama
apple-health-export-mcp

apple-health-export-mcp

by burakdirin

apple-health-export-mcp

CI PyPI Python License: MIT

An MCP server that lets an AI assistant query your Apple Health data — sleep, heart rate, steps, body mass, workouts, and any other metric in your export.

Apple has no live export API, so this works on a snapshot: you export your health archive once, ingest it into a local SQLite database, then the server answers queries against it. See docs/adr.md for why.

Privacy: your health data never leaves your machine and is never committed to git (.gitignore excludes *.zip / *.db).

How it works

export.zip ──(ingest, one-time ~1-3 min)──► health.db (SQLite) ──◄── MCP server queries

Related MCP server: Apple Health MCP

Setup

  1. Export your data on iPhone: Settings → Health → tap your photo → Export All Health Data. AirDrop/save the resulting export.zip.

  2. Install with uv. Installing once (rather than uvx on every launch) keeps the process tree shallow, which matters for clean shutdown — see Shutdown & process model.

    uv tool install apple-health-export-mcp
    # …or from source:
    uv tool install git+https://github.com/burakdirin/apple-health-export-mcp

    This puts two commands on your PATH: apple-health-export-mcp (the server) and apple-health-export-mcp-ingest.

  3. Ingest the archive (one time per new export):

    AH_DB_PATH=~/.local/share/apple-health-export-mcp/health.db \
      apple-health-export-mcp-ingest ~/Downloads/export.zip
  4. Add to your MCP client (e.g. Claude Code .mcp.json). The bare command starts the stdio server; point it at the DB you just built.

    Installed (recommended) — invoke the binary directly (no wrapper process):

    {
      "mcpServers": {
        "apple-health": {
          "command": "apple-health-export-mcp",
          "env": { "AH_DB_PATH": "/Users/you/.local/share/apple-health-export-mcp/health.db" }
        }
      }
    }

    Use an absolute path to the binary (which apple-health-export-mcp) if your client doesn't inherit your PATH.

    Or via uvx (no install; the bare package name runs the server):

    {
      "mcpServers": {
        "apple-health": {
          "command": "uvx",
          "args": ["apple-health-export-mcp"],
          "env": { "AH_DB_PATH": "/Users/you/.local/share/apple-health-export-mcp/health.db" }
        }
      }
    }

    claude mcp add equivalent:

    claude mcp add apple-health --env AH_DB_PATH=~/.local/share/apple-health-export-mcp/health.db \
      -- apple-health-export-mcp

Shutdown & process model

The server is a single process that shuts down on stdin EOF — the MCP spec's primary shutdown signal — so closing your client terminates it cleanly. Avoid extra wrapper layers (uv run … fastmcp run …): uv/uvx stay in the process tree as a parent and only conditionally forward signals, so a wrapped server can be orphaned when the client exits or you press Ctrl+C. Installing the tool and launching the binary directly (config above) gives the shallowest tree and the most reliable cleanup. fastmcp run fastmcp.json is for local dev only.

Tools

Tool

Returns

list_types()

Which metrics exist in your data + row counts and date spans (discovery)

list_sources(type)

Which devices/apps wrote a metric (counts, date spans)

get_quantity(type, start, end, agg, bucket, source)

Per day/week/month/all aggregate for a numeric metric (steps, HR, weight…)

get_sleep(start, end)

Per-night sleep stage durations

get_workouts(start, end)

Workout summary per activity type in the range

All query tools require a date range and return aggregates only — never raw rows (ADR-0008). get_quantity with agg="sum" auto-deduplicates parallel devices (Watch + iPhone + apps) so totals aren't inflated (ADR-0010); pass source (see list_sources) to force one device.

Prompts

Reusable coaching workflows the client can invoke (they orchestrate the tools and reply in your language):

Prompt

Purpose

daily_summary(day?)

One day's snapshot

weekly_review(week_of?)

Calendar week (Mon–Sun): load vs recovery + advice

monthly_summary(month?)

A month in review (YYYY-MM)

yearly_summary(year?)

A year's fitness trajectory (YYYY)

readiness_check()

Train hard today? From sleep + recovery markers

sleep_report(start?, end?)

Sleep duration, stages, consistency

Arguments are optional — they default to today / this week / this month / this year.

Development

uv sync
uv run pytest
uv run ruff check

License

MIT

Available Tools

5 tools
get_quantityA
Read-onlyIdempotent

Aggregate a numeric metric (steps, weight, heart rate, energy…) over a date range.

Call list_types first to find the exact type string. Pick agg by metric kind: sum for cumulative (steps, active energy), avg for sampled (weight, heart rate). sum auto-deduplicates parallel devices (Watch + iPhone + apps) per day, so it does not over-count (ADR-0010); pass source to force one device. avg/min/max are not deduped. Returns [{period, value, n}].

Inputs: end (required), type (required), start (required), agg, +2 more. Returns: result

get_sleepA
Read-onlyIdempotent

Per-night sleep stage durations (minutes), attributed to the wake-up day.

Returns [{night, asleep_min, rem_min, deep_min, core_min, awake_min, in_bed_min}]. Older nights may report only in_bed_min (legacy devices lack stage detail).

Inputs: end (required), start (required). Returns: result

get_workoutsA
Read-onlyIdempotent

Workout summary per activity type in a date range: count, total & avg minutes.

Inputs: end (required), start (required). Returns: result

list_sourcesA
Read-onlyIdempotent

List which sources/devices wrote a metric, with counts and date spans.

Use it to see why a sum differs across devices, or to pick a source for get_quantity.

Inputs: type (required). Returns: result

list_typesA
Read-onlyIdempotent

List which health metrics exist in this export, with row counts and date spans.

Call this first to discover the exact type strings to pass to get_quantity.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: get_quantity aggregates numeric metrics, get_sleep handles sleep stages, get_workouts summarizes workouts, list_sources lists devices, and list_types enumerates health metrics. No overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern using snake_case (e.g., get_quantity, list_sources). There is no variation in style or convention.

    Tool Count5/5

    With 5 tools, the server is well-scoped for a health data export interface. Each tool serves a distinct purpose without redundancy, and the count is neither too sparse nor too heavy.

    Completeness5/5

    The tool surface covers key health data access: numeric metrics (get_quantity), sleep (get_sleep), workouts (get_workouts), source discovery (list_sources), and type discovery (list_types). This set supports common queries without obvious gaps for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables users to query Apple Health metrics, workouts, and trends from CSV files exported via the Health Auto Export app. It allows MCP clients to analyze health data such as heart rate, sleep stages, and activity levels directly from local iCloud Drive storage.
      3
      9 npm
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local-first MCP server that reads Apple Health export files (export.xml/zip) and exposes activity, sleep, HRV, and workout data to AI agents, keeping all data on your machine.
      18
      260 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Query Apple Health export data with an LLM via a semantic layer that avoids common data traps, enabling accurate natural-language queries about health metrics. Optionally imports CPAP therapy data for correlation.
      3
      MIT