apple-health-mcp-server 0.1.0

Probably the most complete Apple Health MCP server

apple-health-mcp-server

Probably the most complete Apple Health MCP server.

Read this in English / 日本語.

apple-health-mcp-server exposes the contents of your Apple Health export (export.xml plus the ECG CSV and GPX route files Apple ships alongside it) to any Model Context Protocol client — including Claude Desktop — through 17 read-oriented tools backed by a local DuckDB database.

Features

• Comprehensive ingestion. Imports Record, Workout (with WorkoutEvent, WorkoutStatistics, WorkoutRoute, and WorkoutMetadataEntry), ActivitySummary, Correlation, Me, ExportDate, ECG voltage samples, and GPX route points. Categorical state-of-mind entries (iOS 17+) land in a dedicated table.
• All data stays local — no external transmission. The importer reads files from disk, the server speaks MCP over stdio (HTTP is opt-in), and the only network artefact is whatever the client itself decides to send.
• DuckDB-backed. Re-imports are idempotent thanks to deterministic deduplication; ad-hoc analysis through run_custom_query runs at native DuckDB speed.
• Time-zone aware. GPX route timestamps are aligned to each parent workout's local offset so joins against XML-derived rows are clean.
• Cross-platform. Tested on Ubuntu, macOS, and Windows against Python 3.12 / 3.13 / 3.14.
• 100% branch-tested. Every release gates on full coverage with pytest --cov-branch --cov-fail-under=100.

Installation

The recommended entry point is uvx, which fetches a one-shot virtualenv on demand and never pollutes the system Python:

uvx apple-health-mcp-server --help

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "apple-health": {
      "command": "uvx",
      "args": ["apple-health-mcp-server", "serve"]
    }
  }
}

Restart Claude Desktop. Before the tools return anything useful, import your data once:

uvx apple-health-mcp-server import /path/to/apple_health_export

The expected directory is the one Apple Health unzips for you (it contains export.xml, an electrocardiograms/ folder, and a workout-routes/ folder).

Database location

By default the database lands at the XDG-resolved data directory:

• Linux / macOS: ~/.local/share/apple-health-mcp/health.duckdb
• Windows: %LOCALAPPDATA%\apple-health-mcp\health.duckdb

Override with --db /custom/path/health.duckdb on either subcommand.

Tools

17 tools are registered with FastMCP, grouped by family:

Family	Tools
Record types & data	list_record_types, query_records, get_record_statistics
Workouts	list_workouts, get_workout_details, get_workout_route
Activity summaries	get_activity_summaries
Heart rate	get_heart_rate_samples
Correlations	list_correlations, get_correlation_details
ECG	list_ecg_readings, get_ecg_data
State of mind	list_state_of_mind
Me characteristics	get_me_attributes
Metadata & ops	list_data_sources, get_import_history
Escape hatch	run_custom_query (read-only validated SQL)

Updating

uvx caches the package on first run and re-uses that cached copy on subsequent invocations, so a new release does not install itself automatically. Pick one:

• Always run the latest — pass --refresh once whenever you want to pull a newer version:

  uvx --refresh apple-health-mcp-server serve
  

• Pin a specific version — write the version directly in your Claude Desktop / Codex / Cursor config so an unrelated uvx cache eviction cannot move you off it:

  {
    "mcpServers": {
      "apple-health": {
        "command": "uvx",
        "args": ["apple-health-mcp-server==0.1.0", "serve"]
      }
    }
  }
  

See CHANGELOG.md for the per-release notes.

Development

uv sync
uv run pytest

See CLAUDE.md for the full command list, conventions, and the mandatory /code-review --fix policy on every pull request.

Contributing

Issues and pull requests in English or Japanese are both first class; see CLAUDE.md §6 for the full language policy.

License

MIT