Skip to main content
Glama
Apple Health MCP Server

Apple Health MCP Server

Apple Health MCP Server

npm version License: MIT

Query Apple Health data from an MCP client using SQL and DuckDB. The server runs locally, reads CSV exports on demand, and provides tools for schema discovery, analytical queries, and health summaries.

Requirements

The native Apple Health export.xml format is not currently supported.

Related MCP server: apple-mcp

Configure an MCP client

For Claude Desktop, add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["-y", "@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/path/to/your/unzipped/health-export"
      }
    }
  }
}

Restart the client after changing its configuration. Other MCP clients can use the same command, arguments, environment, and stdio transport.

Environment variables

Variable

Required

Default

Purpose

HEALTH_DATA_DIR

Yes

—

Directory containing the exported CSV files

MAX_MEMORY_MB

No

2048

DuckDB memory limit in megabytes

CACHE_SIZE

No

100

Maximum number of cached query results

Export health data

  1. Install and open Simple Health Export CSV on your iPhone.

  2. Select All and choose the time range to export.

  3. Transfer the archive to the computer running your MCP client.

  4. Unzip it and set HEALTH_DATA_DIR to the resulting directory.

The server reads the files in place. It does not upload the export or make network requests, although query results returned to your MCP client may be sent to that client's configured model provider.

Tools

Tool

Purpose

health_schema

Discover table names, columns, units, and sample rows

health_query

Run one DuckDB SELECT-family analytical statement with JSON, CSV, or summary output

health_report

Generate a weekly, monthly, or custom health summary

Start with health_schema; table names depend on the files in your export. See Querying Apple Health data for the data model and working examples.

health_query accepts one DuckDB analytical statement. See Query safeguards for supported statements and restricted operations.

Query safeguards

The server limits DuckDB file access to HEALTH_DATA_DIR. It also disables network access and temporary disk storage, and it locks the database settings. The data directory stays readable and writable so the importer can read CSV files.

These controls reduce accidental side effects from generated SQL. They do not isolate the process. Run the server through a local stdio MCP client. Do not expose it to an untrusted network client. Use process or OS isolation if the server must accept untrusted SQL.

History and memory

The first request that needs a table loads that table's full CSV history. There is no date window, so a query can reach as far back as the export goes.

Because every tool can reach the whole configured history, only start this server from an MCP client you trust with that data.

Loaded tables are held in memory, and DuckDB is given the MAX_MEMORY_MB limit described above. Roughly 1 GiB covers a two-year multi-table export, so the 2048MB default leaves headroom; raise MAX_MEMORY_MB for a larger export. The server never spills health rows to a temporary directory on disk, so an export that does not fit in the limit fails with an explicit error instead.

Other current limitations:

  • Only the Simple Health Export CSV layout is supported.

  • The DuckDB database is in memory and is rebuilt for each server process, so each launch reloads from the CSV files. Persistent incremental import is planned future work, not current behavior.

  • Device overlap can produce duplicate-looking measurements; queries should account for sourceName where appropriate.

  • Health reports summarize recorded data and are not medical advice.

Development

git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install

npm test
npm run typecheck
npm run build

See Architecture for the code layout, data lifecycle, and implementation constraints. See Release procedure for publishing and recovery steps.

License

MIT

Available Tools

3 tools
health_queryB

Run one analytical query on Apple Health data.

Inputs: query (required), format.

health_reportB

Generate structured health reports for a specific period

Inputs: report_type (required), end_date, start_date, include_metrics.

health_schemaA

Get information about available health data tables, their structure, and sample data to help write SQL queries

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: health_query runs analytical queries, health_report generates reports, and health_schema provides metadata about tables. There is no overlap in functionality.

    Naming Consistency5/5

    All tools follow a consistent pattern with the prefix 'health_' followed by a clear noun (query, report, schema). Naming is uniform and predictable.

    Tool Count4/5

    With only 3 tools, the set is compact but well-scoped for the stated analytical purpose. While slightly minimal, each tool earns its place and doesn't feel overly sparse.

    Completeness4/5

    The tools cover the essential analytical workflow: querying data, generating reports, and understanding schema. Minor gaps exist (e.g., no direct data export), but for the apparent read-only analytical scope, coverage is sufficient.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity, and HRV data. Tokens never leave your machine.
      27
      439 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Open-source MCP server for MetricBridge (formerly Health Export AI). 16 tools and 22 prompts let any MCP agent query 190 Apple Health metrics from files on your own machine. The server is read-only, has zero dependencies and makes zero network calls.
      21
      561 npm
      11
      MIT