Skip to main content
Glama
daveremy

Apple Health MCP

by daveremy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

apple-health-mcp

An MCP server for Apple Health data. Reads daily health metrics and workouts exported by the Health Auto Export iOS app.

Features

  • MCP Server: 3 tools for querying Apple Health data from Claude Code or any MCP client

  • No API keys needed: Reads local CSV files exported by Health Auto Export to iCloud Drive

  • Comprehensive: Steps, HR, HRV, SpO2, sleep stages, body composition, workouts

Related MCP server: Apple Health MCP

MCP Tools

Tool

Description

apple_health_daily

Daily summary: steps, energy, HR, HRV, sleep stages, body comp, workouts

apple_health_workouts

Workout sessions for a date (type, duration, HR, calories, distance)

apple_health_trends

Multi-day trends for steps, HR, HRV, sleep, weight

Setup

1. Set up Health Auto Export on iPhone

This MCP server reads CSV files produced by Health Auto Export, a third-party iOS app that automatically exports Apple Health data to iCloud Drive. The app runs in the background and syncs new data throughout the day.

  1. Install Health Auto Export from the App Store

  2. Open the app and grant it access to Apple Health data when prompted

  3. Go to Automations and create two automations:

    • Daily Metrics: Select the health metrics you want (steps, heart rate, sleep, etc.), set format to CSV, frequency to Daily, and destination to iCloud Drive

    • Workouts: Select workout data, set format to CSV, frequency to Daily, and destination to iCloud Drive

  4. The app will export CSV files to iCloud Drive, which syncs automatically to your Mac at:

    ~/Library/Mobile Documents/iCloud~com~ifunography~HealthExport/Documents/

  5. Verify the files are syncing by checking that the directory contains Daily Export/ and Workouts/ folders with dated CSV files

2. Install

git clone https://github.com/daveremy/apple-health-mcp.git
cd apple-health-mcp
npm install
npm run build

3. Use as MCP Server

Add to your Claude Code project's .mcp.json:

{
  "mcpServers": {
    "apple-health": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/apple-health-mcp/dist/mcp.js"]
    }
  }
}

Or register with the Claude CLI:

claude mcp add apple-health --scope project -- node /path/to/apple-health-mcp/dist/mcp.js

Custom Export Directory

If your Health Auto Export saves to a different location, set the environment variable:

{
  "env": {
    "APPLE_HEALTH_EXPORT_DIR": "/path/to/your/export/directory"
  }
}

Data Format

The server expects the CSV file structure produced by Health Auto Export:

Documents/
  Daily Export/
    HealthMetrics-YYYY-MM-DD.csv
  Workouts/
    Workouts-YYYY-MM-DD.csv

Requirements

License

MIT

Available Tools

3 tools
apple_health_dailyDaily SummaryB

Get Apple Health daily summary: steps, energy, HR, HRV, sleep stages, body comp, workouts

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoYYYY-MM-DD, defaults to today

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full disclosure burden. It enumerates the data categories returned, which helps understand scope. However, it lacks behavioral details such as error handling for future dates, privacy/auth requirements, data availability when Health permissions are denied, or whether values are summed/averaged.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single efficient sentence front-loaded with the action. The colon-separated list of metrics is compact and readable. No extraneous text, though slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without output schema, the description adequately compensates by listing the seven metric categories returned. However, for a health data tool with no annotations, it should clarify behavior regarding missing data (null values vs zeros) and permission requirements to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage (date field fully documented with format and default), establishing baseline 3. Description does not add semantic context about the date parameter (e.g., timezone handling, how 'today' is determined), but none is required given complete schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses specific verb 'Get' and resource 'Apple Health daily summary'. Lists specific metric categories (steps, energy, HR, HRV, sleep stages, body comp, workouts) clarifying scope. However, it does not explicitly differentiate from sibling 'apple_health_workouts' despite mentioning workouts in its data list, nor contrast with 'apple_health_trends'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use this tool versus the sibling 'trends' or 'workouts' tools. The inclusion of 'workouts' in the daily summary list without qualification creates potential ambiguity about whether this returns summary workout statistics or detailed records.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

apple_health_workoutsWorkoutsC

Get workout sessions for a date

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoYYYY-MM-DD, defaults to today

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full disclosure burden. 'Get' implies read-only safety, but description omits what data structure returns (list of workouts, duration, types, calories), behavior when no workouts exist, or whether this includes all activity types. No output schema compounds this gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (6 words) and front-loaded with verb-first structure. No redundant phrases. However, brevity arguably underserves tool's behavioral complexity given lack of annotations and output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Acceptable for a single-parameter tool with 100% schema coverage, but gaps remain. Missing: return value description (critical without output schema), explicit sibling differentiation, and confirmation of read-only behavior. Minimum viable but not exemplary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (date parameter fully documented with format and default). Description references 'a date' acknowledging the parameter exists, but adds no semantic detail beyond schema's 'YYYY-MM-DD, defaults to today'. Baseline score appropriate given schema completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'Get' and resource 'workout sessions'. Scope 'for a date' implies filtering by specific date. Implicitly distinguishes from siblings by focusing on individual sessions vs aggregates (daily/trends), though explicit differentiation would strengthen this.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus apple_health_daily or apple_health_trends. Agent must infer that 'workouts' retrieves individual exercise sessions while siblings handle aggregated metrics. No mention of prerequisites or date range limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedapple_health_daily
    • First observedapple_health_trends
    • First observedapple_health_workouts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation4/5

The three tools have distinct primary purposes: daily summary, trends over a range, and workouts. However, apple_health_daily and apple_health_trends overlap significantly in metrics (steps, HR, HRV, sleep), which could cause confusion about when to use each. The descriptions help clarify, but some ambiguity remains.

Naming Consistency5/5

All tool names follow a consistent apple_health_* pattern with clear, descriptive suffixes (daily, trends, workouts). This predictable naming makes it easy for agents to understand the tool set and infer purposes without confusion.

Tool Count3/5

With only 3 tools, the server feels thin for the Apple Health domain, which typically includes more operations like adding data, querying specific metrics, or managing permissions. While it covers basic retrieval, the scope seems limited compared to the potential complexity of health data.

Completeness2/5

The tool set is severely incomplete for an Apple Health server, focusing only on retrieval of daily summaries, trends, and workouts. There are no tools for creating, updating, or deleting health data, nor for accessing detailed metrics or settings, which are common in health APIs. This will likely cause agent failures in broader health management tasks.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Apple Health MCP

    davidmosiah
    A
    license
    A
    quality
    A
    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
    169 npm
    2
    MIT

  • Apple Health Chat MCP

    gh33k
    F
    license
    B
    quality
    D
    maintenance
    Enables Claude to answer natural language questions about your Apple Health data by analyzing local CSV exports, supporting metrics like steps, heart rate, sleep, and more.
    6
    2
    -

  • Health Export AI

    PhilipAD
    A
    license
    A
    quality
    A
    maintenance
    An MCP server that enables AI agents to query Apple Health data (190+ metrics) in natural language, including trends, comparisons, and structured exports.
    14
    119 npm
    4
    MIT