What can you do with this server?

This MCP server lets you query and analyze your Apple Health data from a Postgres database using natural language via any MCP-compatible AI client. Key capabilities include: * Get a health summary (get_health_summary): Overview of key metrics (steps, sleep, HRV, resting HR, workouts) for a specified number of days. * Analyze sleep (get_sleep): Per-night sleep breakdown with stage durations (REM, Deep/Core, Light, Awake). * Track HRV trends (get_hrv_trend): Daily HRV averages, rolling comparisons, and trend direction. * Query any HealthKit metric (query_metric): Raw time-series data or daily aggregates for any metric type. * View workouts (get_workouts): Recent workout details including type, duration, distance, and calories. * Get a daily snapshot (get_daily_snapshot): All recorded health data for a specific date. * Analyze long-term trends (get_long_term_trend): Multi-year or seasonal trends using raw and summarized data. * Generate a coaching brief (get_coaching_brief): Structured summary of recovery, sleep, training load, and fitness trajectory. * Search records by threshold (search_records): Days where a metric crossed a min/max value. * Calculate metric statistics (get_metric_stats): Personal baselines (min, max, mean, percentiles) for any metric. * Compare time periods (compare_periods): Compare a metric between two custom date ranges with stats and deltas.

Which integrations are available for this server?

Access Apple Health data including sleep stages, HRV, heart rate, workouts, VO₂ max, and over 150 other metrics for AI-powered analysis. Sync health data from iPhone HealthKit to a user-owned Postgres database using a native iOS app with background sync.

Health4AI

by jefflitt1

Overview Schema Source Related Servers Discussions Admin

Remote

health4.ai — Apple Health × AI

What it does

iPhone HealthKit → Your Postgres database → MCP server → Any AI

Apple Health holds years of your biometric data — sleep stages, HRV, heart rate, workouts, VO₂ max, and 150+ other metrics. health4.ai makes all of it queryable from Claude, ChatGPT, Cursor, Ollama, or any MCP-compatible client via 8 purpose-built tools.

You control the data. It syncs to a Postgres database you configure — Supabase, Neon, or a local Docker container. health4.ai never stores or has access to your health data.

Related MCP server: Health Export AI

Why it exists

Problem	health4.ai fix
Apple has no HealthKit server API — all access requires an on-device app	Native iOS app with `HKObserverQuery` + `BGTaskScheduler` background sync
Health Auto Export only works on the same WiFi	Your data lands in Postgres — queryable from any AI, anywhere
The claude.ai Apple Health connector doesn't reach Claude Code CLI or Cursor	Standard MCP (stdio) — one config block works everywhere
Most solutions require a managed cloud service	Bring your own Postgres: Supabase, Neon, or fully local

Demo

Demo video coming. Here's what a typical conversation looks like:

You:     How was my recovery this week? Anything standing out?

Claude:  Your recovery this week was mixed but trending positive.
         • HRV averaged 58ms (Tue–Thu strong at 64–68ms; Monday low at 44ms after Saturday's long run)
         • Sleep averaged 7h 12m — Wednesday and Thursday were your best nights (7h 40m+)
         • Resting HR dropped from 54bpm Monday to 49bpm Friday — a good sign
         Recommendation: today looks like a solid day for a moderate-intensity session.

Quick start

Choose your Postgres backend first:

# 1. Create a project at supabase.com
# 2. Run the schema
psql "$DATABASE_URL" < web/public/schema.sql
# or use the Supabase dashboard SQL editor

# 1. Create a project at neon.tech
# 2. Run the schema
psql "$DATABASE_URL" < web/public/schema.sql

docker run -d \
  --name health4ai-postgres \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  postgres:16
psql "postgresql://postgres:yourpassword@localhost:5432/postgres" \
  < web/public/schema.sql

Then set up the MCP server:

git clone https://github.com/jefflitt1/health4ai.git
cd health4ai

cp mcp-server/.env.example mcp-server/.env

Edit mcp-server/.env:

DATABASE_URL=postgresql://...    # your Postgres connection string
HEALTHKIT_USER_ID=your_user_id   # any string to identify your data

Add to your AI client:

{
  "mcpServers": {
    "health4ai": {
      "command": "python",
      "args": ["/path/to/health4ai/mcp-server/main.py"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "HEALTHKIT_USER_ID": "your_user_id"
      }
    }
  }
}

Same block → ~/.cursor/mcp.json

Pair with mcphost or mcp-client-for-ollama:

mcphost --model ollama/llama3.2 \
  --mcp-server "health4ai:python /path/to/health4ai/mcp-server/main.py"

Your health data and the model both stay on your hardware — nothing leaves your machine.

Install the iOS app: Configure a database and Supabase account that you control, then sign in and tap Start Sync. For a private TestFlight beta, follow the tester-isolation guide; never use another person's backend or credentials.

MCP tools

Tool	What it answers
`get_health_summary`	Overview of key metrics for the past N days
`get_sleep`	Per-night sleep breakdown with REM, Deep, Core stages
`get_hrv_trend`	Daily HRV (SDNN) with rolling comparison and trend
`get_daily_snapshot`	Everything recorded for a specific date
`get_workouts`	Recent workouts with type, duration, distance, calories
`query_metric`	Raw time-series for any HealthKit metric type
`get_long_term_trend`	Monthly aggregates over years (raw + summary tiers)
`get_coaching_brief`	Recovery status, sleep quality, training load, fitness markers
`search_records`	Find days where a metric crossed a threshold
`get_metric_stats`	Personal baseline: min/max/mean/percentiles
`compare_periods`	Compare a metric between two date ranges

If a metric is empty, read `data_status` before believing it

iOS never tells an app that a Health permission was denied. A type you have not shared returns an empty result, byte-for-byte identical to a day where you genuinely did nothing. Nothing in HealthKit's API can distinguish the two, so an assistant reading a bare 0 will confidently tell you that you took no steps.

Tools that can return an empty result therefore attach a data_status block:

never_recorded — this metric has never produced a sample for you. For steps, heart rate, active energy or walking distance that is not possible if the data were being shared, so it almost certainly is not. Open Health → Sharing → Apps → health4ai, switch the metric on, then re-run the import from the app's Home tab.
empty_window — nothing in the window you asked about, but the metric has data at other times. A real gap, not a permission problem.

This is not hypothetical. On the author's own account, step count, heart rate, active energy and walking distance were silently unshared for nearly three months while every other metric synced normally, and the app displayed a green "Complete" throughout.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  iPhone                                                      │
│  HKObserverQuery + BGTaskScheduler                          │
│  → continuous background sync                               │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Your Postgres database (Supabase / Neon / local Docker)    │
│  healthkit_metrics · healthkit_daily_summaries              │
│  v_healthkit_daily_quantity (unified view)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │ SQL (service-role key, server-side only)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  FastMCP server  (mcp-server/main.py)                       │
│  11 tools · stdio transport                                  │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP
                           ▼
              Claude · ChatGPT · Cursor · Ollama · any client

Data tiers: queries within the last 30 days return raw samples; older data transparently switches to pre-aggregated daily summaries — so long-term trend queries stay fast regardless of data volume.

Repo structure

health4ai/
├── ios/                         # Swift/SwiftUI iOS app (iOS 17+)
│   └── Health4AI/               # HealthKit sync engine, auth, settings
├── mcp-server/
│   ├── main.py                  # FastMCP server entry point
│   ├── tools.py                 # 11 tool implementations
│   └── .env.example             # Required environment variables
├── web/
│   ├── public/schema.sql        # Portable Postgres schema (all backends)
│   └── src/                     # Astro marketing site
├── scripts/
│   ├── import_health_export.py  # One-time XML backfill from Apple Health export
│   └── summarize_historical.py  # Backfill daily summaries table
└── docs/
    └── SETUP.md                 # Detailed setup guide

Privacy

Your health data goes directly from your iPhone to your Postgres database. health4.ai never receives, stores, or has access to it. The MCP server runs locally with your own credentials — your data never touches our infrastructure.

See the Privacy Policy for full details.

Contributing

MIT licensed. PRs welcome.

Good first areas: additional metric aggregations, multi-user support with JWT/RLS, Android, and more MCP client integration guides.

License

MIT — see LICENSE.

Available Tools

11 tools

compare_periodsA

Compare a health metric between two date ranges. Dates: YYYY-MM-DD.

Examples:

Sleep before vs after starting magnesium: period_a = two weeks before, period_b = two weeks after
HRV this month vs last month: period_a_start='2026-05-01', period_a_end='2026-05-31', period_b_start='2026-06-01', period_b_end='2026-06-18'
Steps during a work trip vs home baseline

Returns per-period stats and a delta showing which period was better.

ParametersJSON Schema

Name	Required	Default
`metric_type`	Yes
`period_a_start`	Yes
`period_a_end`	Yes
`period_b_start`	Yes
`period_b_end`	Yes
`label_a`	No	Period A
`label_b`	No	Period B

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description bears full responsibility. It notes the date format and states the tool returns per-period stats and a delta, but does not disclose potential side effects, authentication requirements, or rate limits.

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?

The description is efficiently structured with the main purpose first, followed by examples. It is slightly verbose with multiple examples, but each adds value. No unnecessary sentences.

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

Completeness4/5

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

Given the tool has 7 parameters and no schema descriptions, the description adequately covers the inputs. It also mentions the output schema exists, reducing the need to detail return values. Slightly less complete due to missing behavioral details.

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

Parameters5/5

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

Schema coverage is 0% with no parameter descriptions. The description adds significant meaning by explaining each parameter through examples, covering metric_type, date ranges, and labels, thus fully compensating for the lack of schema documentation.

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

Purpose5/5

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

The description clearly states the tool compares a health metric between two date ranges, using specific verbs and resources. It distinguishes itself from sibling tools like 'get_metric_stats' and 'query_metric' by focusing on period comparison.

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

Usage Guidelines4/5

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

The description provides relevant examples of when to use the tool (e.g., sleep before/after supplements, month-over-month HRV). However, it does not explicitly exclude alternative tools or give when-not-to-use guidance.

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

get_coaching_briefA

Pre-session coaching brief for Brett — combines recent trends across all key metrics. Returns a structured summary optimized for performance coaching context: recovery status, sleep quality, training load, and fitness trajectory. Call this at the start of every coaching session.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description must carry the full burden. It explains the tool combines recent trends and returns a structured summary, listing key fields. It does not disclose whether the operation is read-only, nor any side effects, auth requirements, or rate limits. The fact that an output schema exists (unseen here) could supplement, but the description alone is moderately transparent.

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

Conciseness5/5

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

The description is three sentences long, front-loaded with the purpose, followed by output details and usage guidance. Every sentence adds value without redundancy or fluff, making it highly concise and well-structured.

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

Completeness4/5

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

Given the tool has no parameters and an output schema exists, the description covers its purpose, output content, and usage timing adequately. It lacks details on any prerequisites, data freshness, or personalization scope, but for a pre-session brief, the provided context is largely sufficient.

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

Parameters4/5

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

The input schema has zero parameters, so parameter semantics are not applicable. According to guidelines, baseline score is 4. The description does not need to add parameter info, and it doesn't, which is appropriate.

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

Purpose5/5

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

The description clearly states the tool provides a pre-session coaching brief for Brett, combining recent trends across key metrics. It specifies the output includes recovery status, sleep quality, training load, and fitness trajectory, distinguishing it from sibling tools like 'get_daily_snapshot' or 'get_health_summary' by its personalized and coaching-specific focus.

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

Usage Guidelines4/5

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

The description explicitly directs calling this tool 'at the start of every coaching session,' providing clear context for when to use it. However, it does not mention when not to use it or compare directly with alternatives, though the sibling tools list implies other options exist.

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

get_daily_snapshotA

Everything recorded for a specific date (YYYY-MM-DD). Defaults to today. Returns steps, sleep, workouts, HRV, resting HR, active energy, and all other metrics.

ParametersJSON Schema

Name	Required	Description	Default
`date`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior2/5

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

With no annotations, the description carries the full burden. It mentions default behavior and return metrics but lacks disclosure on safety (read-only), error handling (e.g., missing data), or authentication requirements.

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

Conciseness5/5

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

Two concise sentences front-load key information (date format, default, returned metrics) with no wasted words.

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?

The output schema exists, so return values are covered. However, with no annotations and moderate sibling count, the description should address behavioral context more thoroughly, such as read-only nature or data availability.

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

Parameters4/5

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

The input schema has 0% coverage, but the description adds format (YYYY-MM-DD) and default behavior. This compensates well for the single parameter, though it could clarify optionality explicitly.

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

Purpose5/5

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

The description clearly states the tool retrieves all metrics for a specific date, listing examples like steps, sleep, and HRV, which distinguishes it from more specific sibling tools like get_sleep or get_workouts.

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

Usage Guidelines3/5

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

The description implies use for a full daily summary and notes the default to today, but does not explicitly guide when to use alternatives like get_sleep or get_hrv_trend for specific metrics.

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

get_health_summaryA

Overview of key health metrics for the past N days. Returns avg steps, avg sleep, avg HRV, avg resting HR, workout count.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations provided, the description takes the full burden. It lists what metrics are returned but does not disclose behavior for missing data, edge cases, or whether the operation is read-only (though implied). No contradictions.

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?

The description is two sentences and directly states the purpose and returned metrics. It is concise but could be structured slightly better (e.g., listing metrics in a clearer format).

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

Completeness4/5

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

Given the existence of an output schema (not shown), the description sufficiently covers the return values. It also differentiates from the many sibling tools. However, it could mention use cases or limitations for completeness.

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 description coverage is 0%, so the description must explain the 'days' parameter. It indicates 'past N days', which adds context beyond the schema, but lacks details like inclusivity or date range formatting. Baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states it returns an overview of key health metrics (avg steps, sleep, HRV, resting HR, workout count) for the past N days. This distinguishes it from sibling tools that focus on individual metrics or comparisons.

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

Usage Guidelines3/5

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

The description implies usage for getting a broad summary, but does not explicitly state when to use this vs alternatives like get_sleep or get_workouts. No 'when not to use' guidance is provided.

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

get_hrv_trendA

HRV (SDNN) trend over the past N days. Returns daily averages, 7-day rolling comparison, and trend direction. Tier-aware: windows beyond 30 days transparently use daily summaries.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses the data returned and the tier-aware behavior for windows beyond 30 days. However, it does not mention auth requirements, rate limits, or potential side effects, leaving some behavioral aspects unclear.

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

Conciseness5/5

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

Three sentences, each serving a distinct purpose: stating the tool's function, listing outputs, and noting a technical detail. No extraneous words, and the most important information is front-loaded.

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

Completeness4/5

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

Given the tool's simplicity (1 parameter, output schema exists), the description covers the main aspects: what is returned, the parameter's meaning, and a note on data aggregation for longer windows. It does not repeat return format details since an output schema is present.

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

Parameters4/5

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

The single parameter 'days' has no schema description (0% coverage). The description adds context by mentioning 'past N days' and 'windows beyond 30 days', helping the agent understand the parameter's effect and the scaling behavior.

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

Purpose5/5

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

The description specifies the verb 'get trend', the resource 'HRV (SDNN)', and the scope 'past N days'. It lists the returned components: daily averages, 7-day rolling comparison, trend direction. This clearly distinguishes it from siblings like get_long_term_trend or query_metric.

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

Usage Guidelines3/5

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

The description implies usage for HRV trend analysis but does not explicitly state when to use this tool versus alternatives such as get_long_term_trend or get_metric_stats. No when-not-to-use or alternative recommendations are provided.

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

get_long_term_trendA

Long-term trend for any metric. Tier-aware: merges recent raw data (last 30 days, aggregated to daily) with historical daily summaries, so the trend has no recency gap. Best for multi-year / seasonal analysis. metric_type examples: HKQuantityTypeIdentifierHeartRateVariabilitySDNN, HKQuantityTypeIdentifierRestingHeartRate, HKQuantityTypeIdentifierBodyMass, HKQuantityTypeIdentifierStepCount months: how many months of history to return (default 24)

ParametersJSON Schema

Name	Required	Description	Default
`metric_type`	Yes
`months`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries full behavioral burden. It discloses the tier-aware merging behavior and the recency gap closure, which is important for understanding the tool's output. It does not mention authorization or side effects, but those are likely minimal for a read operation. The description adds value beyond the bare schema.

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

Conciseness5/5

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

The description is concise (4 sentences), with the core purpose in the first sentence. Every sentence adds value: purpose, tier-aware behavior, use case, and parameter examples. No wasted words.

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

Completeness4/5

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

The description covers the tool's complexity (merging logic, parameters, usage context). An output schema exists but is not shown; the description does not explain return values, which is acceptable given the schema. Overall, it provides sufficient context for correct tool invocation.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It provides examples for metric_type (e.g., HKQuantityTypeIdentifierHeartRateVariabilitySDNN) and explains the months parameter with its default value (24). While it does not give constraints or a full list, the examples help the agent understand acceptable values.

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

Purpose5/5

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

The description clearly states the tool provides 'Long-term trend for any metric' and explains the tier-aware merging of recent raw data with historical summaries, which distinguishes it from sibling tools like get_hrv_trend (specific to HRV). The verb 'get' and resource 'long-term trend' are specific and unambiguous.

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

Usage Guidelines4/5

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

The description says 'Best for multi-year / seasonal analysis,' which clearly conveys when to use it. It implies a long-term context but does not explicitly mention when not to use or name alternative tools. However, the context is sufficient for an AI agent to infer appropriate usage.

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

get_metric_statsA

Personal baseline statistics for any health metric. Returns min, max, mean, std dev, and percentile distribution (p10-p90).

Use to answer: 'Is today's reading good or bad for me personally?' Pair with get_daily_snapshot to compare today's value against your baseline.

The 'thresholds' field translates percentiles into plain English: good_day_above = your 75th percentile (a genuinely above-average day) poor_day_below = your 25th percentile (a below-average day worth noting)

ParametersJSON Schema

Name	Required	Description	Default
`metric_type`	Yes
`days`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations, the description fully carries the burden. It details the returned statistics, defines the thresholds field in plain English, and explains percentile meanings. However, it does not mention authorization or side effects, which are minimal for a read-only query. The description is transparent about what the tool does and returns.

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

Conciseness5/5

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

The description is concise and well-structured: first sentence states purpose, then lists output, then usage guidance, then threshold explanation. Every sentence adds value, and the most critical information is front-loaded.

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

Completeness5/5

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

Given an output schema exists, the description need not detail return values, but it does so effectively. It explains the thresholds field, suggests a sibling tool, and provides enough context for an agent to use the tool correctly. The description is complete for the tool's 2 parameters and intended use case.

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?

The schema coverage is 0%, so the description must explain parameters. It implicitly covers 'metric_type' via 'any health metric' but does not describe the 'days' parameter despite its default of 90. The description adds value by explaining the thresholds field and percentiles, but fails to fully compensate for the lack of parameter documentation.

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

Purpose5/5

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

The description clearly states the tool provides 'personal baseline statistics for any health metric' and lists specific outputs (min, max, mean, etc.). It distinguishes from sibling tools like get_daily_snapshot by explicitly suggesting pairing, making the purpose unambiguous.

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

Usage Guidelines5/5

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

The description includes explicit usage guidance: 'Use to answer: Is today's reading good or bad for me personally?' and 'Pair with get_daily_snapshot to compare today's value against your baseline.' This tells the agent exactly when and how to use the tool, with no ambiguity.

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

get_sleepA

Sleep analysis for the past N days. Returns per-night breakdown with stage durations (REM, Deep/Core, Light, Awake).

ParametersJSON Schema

Name	Required	Description	Default
`days`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It states the tool returns sleep data and stage durations, which is clear, but it does not mention permissions, rate limits, or data availability constraints.

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

Conciseness5/5

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

Two sentences efficiently convey the tool's purpose and output. The core information is front-loaded with no wasted words.

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

Completeness4/5

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

Given the existence of an output schema (not provided), the description adequately covers the tool's function and main output components. Minor details like max days or edge cases are missing, but it is sufficient for a simple tool.

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

Parameters4/5

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

The description explains the 'days' parameter by mentioning 'past N days', which adds meaning beyond the input schema. With only one simple parameter, this is adequate even with 0% schema description coverage.

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

Purpose5/5

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

The description clearly states the tool provides sleep analysis for the past N days with a per-night breakdown of stage durations (REM, Deep/Core, Light, Awake), which distinguishes it from siblings like get_daily_snapshot or get_health_summary.

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

Usage Guidelines3/5

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

The description implies usage for retrieving sleep data over a range of days but does not explicitly state when to use this tool versus alternatives like get_daily_snapshot or get_health_summary.

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

get_workoutsC

Recent workouts with type, duration, distance, and calories.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.4/5.0

Behavior2/5

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

With no annotations, the description carries full burden. It does not disclose behaviors like authentication needs, rate limits, or whether it only returns a subset of data (e.g., pagination via limit). It only states what fields are returned.

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

Conciseness3/5

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

The description is a single sentence, which is concise but too brief for a tool with two optional parameters. It could add a second sentence explaining parameters without costing conciseness.

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

Completeness2/5

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

Given the presence of an output schema, the description need not detail return values. However, with 0% parameter documentation and no usage guidance, it is incomplete for a tool that has configurable defaults and sibling tools.

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

Parameters1/5

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

Schema description coverage is 0%, yet the description contains no explanation of the two parameters (days and limit). The defaults are in the schema but not mentioned, leaving the agent uninformed about controlling the recency or number of results.

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?

The description clearly states the tool returns recent workouts with specific fields (type, duration, distance, calories). It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like compare_periods or get_daily_snapshot, though the focus on workouts is distinct.

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 is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context such as that it only returns recent data (default 30 days) or any limitations.

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

query_metricB

Time-series for any HealthKit metric type. metric_type: e.g. 'HKQuantityTypeIdentifierStepCount', 'HKQuantityTypeIdentifierHeartRate' Windows <= 30 days return raw samples; longer windows return daily aggregates (raw samples beyond 30 days are summarized and no longer stored individually).

ParametersJSON Schema

Name	Required	Description	Default
`metric_type`	Yes
`days`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.4/5.0

Behavior4/5

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

With no annotations, the description effectively discloses key behaviors: windows <=30 days return raw samples, longer windows return daily aggregates, and raw samples beyond 30 days are summarized. Adds value beyond schema.

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?

Concise (4 lines) with clear structure: purpose statement, examples, then behavioral rules. No fluff, but could be more structured with bullet points.

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?

Covers the main behavioral aspect (window vs aggregation) but partially explains parameters (missing limit). Given it has an output schema, return values need not be detailed, but the tool is fairly simple and the description is sufficient but not rich.

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 description coverage is 0%, so description must compensate. It explains 'metric_type' with examples and implies 'days' controls window length, but does not explain 'limit'. Some added meaning, but not fully comprehensive.

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?

Clearly states the tool retrieves time-series for any HealthKit metric type with examples, but does not explicitly differentiate itself from sibling tools like compare_periods or get_daily_snapshot.

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 tool versus alternatives (e.g., get_daily_snapshot for single-day aggregation, compare_periods for comparisons). The description only provides behavioral details about window sizes.

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

search_recordsA

Find days where a health metric crossed a threshold. For cumulative metrics (steps, calories) filters on daily total. For rate metrics (HRV, heart rate) filters on daily average.

Examples:

All days with HRV below 40ms: metric_type='HKQuantityTypeIdentifierHeartRateVariabilitySDNN', max_value=40
Days with 10k+ steps: metric_type='HKQuantityTypeIdentifierStepCount', min_value=10000
Nights under 6 hours sleep (360 min): metric_type='HKCategoryTypeIdentifierSleepAnalysis', max_value=360

Results sorted highest-to-lowest so outliers surface first.

ParametersJSON Schema

Name	Required	Description	Default
`metric_type`	Yes
`days`	No
`min_value`	No
`max_value`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.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 burden. It explains behavior for cumulative vs. rate metrics and sorting, but lacks details on auth, rate limits, or potential no-match scenarios. Adequate but not comprehensive.

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

Conciseness5/5

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

Concise, well-structured: summary, differentiation of metric types, examples, and sorting behavior. Every sentence adds value with no redundancy.

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

Completeness4/5

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

Given 5 parameters and threshold-based filtering, description covers key aspects. Output schema exists, so return values are handled. Could include handling of no matches, but overall complete.

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

Parameters4/5

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

Schema description coverage is 0%, so description compensates well. It explains min_value/max_value as thresholds and provides examples for metric_type. Does not fully detail days and limit, but clarifies defaults and usage.

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

Purpose5/5

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

The description clearly states the tool finds days where a health metric crossed a threshold, and distinguishes between cumulative and rate metrics. This is specific and distinct from siblings like get_metric_stats or query_metric.

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

Usage Guidelines4/5

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

Provides clear examples of when to use it (e.g., days with HRV below 40ms). Lacks explicit guidance on when not to use it or alternatives, but the context of threshold crossing is well-defined.

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.

11 tool updatesv0.1.1Jun 19, 2026
- First observedcompare_periods
- First observedget_coaching_brief
- First observedget_daily_snapshot
- First observedget_health_summary
- First observedget_hrv_trend
- First observedget_long_term_trend
- First observedget_metric_stats
- First observedget_sleep
- First observedget_workouts
- First observedquery_metric
- First observedsearch_records

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

A3.6/5.0

Scored 2026-06-19 20:10 across 11 tools

Disambiguation4/5

Most tools have distinct purposes like comparing periods, getting daily snapshots, and querying metrics. However, 'get_health_summary' and 'get_daily_snapshot' overlap somewhat in content, and 'get_hrv_trend' is redundant with 'query_metric' for HRV, causing minor ambiguity.

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern in snake_case, with most using 'get_' prefix. 'compare_periods', 'query_metric', and 'search_records' deviate from the 'get_' pattern but still maintain clear verb-first naming, resulting in only minor inconsistency.

Tool Count5/5

11 tools is well-scoped for a health analytics server, covering diverse needs like trend analysis, comparisons, summaries, and searches without being excessive.

Completeness4/5

The tool set provides comprehensive read-only access to health metrics including trend, comparison, stats, and search. Missing write operations (create/update/delete) are acceptable for an analytics-focused server, but there is no correlation or export tool, which could be useful.

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

SomviaOAuth
app.somvia
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Health & Wellness Fitness Tracking
2
Garmin — MissingMCPOAuth
com.missingmcp
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Health & Wellness Fitness Tracking
25
WHOOP — MissingMCPOAuth
com.missingmcp
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Health & Wellness Fitness Tracking
25
MCP for OuraOAuth
link.smirnov
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Health & Wellness Fitness Tracking
2

Related MCP Servers

Apple Health MCP
Health & Wellness Fitness Tracking
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.
Updated 6 days ago (2026-09-07 12:18 UTC)
18
221 npm
2
MIT
Health Export AI
Databases Health & Wellness
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.
Updated 9 days ago (2026-09-03 22:48 UTC)
14
95 npm
3
MIT
apple-health-shortcuts-mcp
Health & Wellness Fitness Tracking
Barbara-105
A
license
Not graded
quality
C
maintenance
Exposes read-only Apple Health data (current status, sleep details, trends) to AI via a Cloudflare-deployed MCP server and iPhone Shortcuts.
Updated a month ago (2026-07-31 05:08 UTC)
MIT
Wellness Project MCP
Health & Wellness Fitness Tracking
turnnoblindeye
A
license
A
quality
A
maintenance
Hosted MCP server that syncs health data from Apple Health, Fitbit, Oura, and Google Health Connect, enabling Claude and ChatGPT to query workouts, sleep, nutrition, and recovery in plain English with interactive charts.
Updated 5 days ago (2026-09-07 23:39 UTC)
2
73
2
MIT

health4.ai — Apple Health × AI

What it does

Why it exists

Demo

Quick start

MCP tools

If a metric is empty, read data_status before believing it

Architecture

Repo structure

Privacy

Contributing

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

If a metric is empty, read `data_status` before believing it