MCP Server Reference

MCP Tools Reference

For developers: once you install the health4.ai app and connect HealthKit, these are the 8 MCP tools your AI can call. Add the server to claude_desktop_config.json with the token from the app — no repo clone, no service keys.

Quick Install

{
  "mcpServers": {
    "health4ai": {
      "command": "npx",
      "args": ["health4ai-mcp"],
      "env": { "HEALTH4AI_TOKEN": "your-token-from-the-app" }
    }
  }
}

The app generates your token after you connect HealthKit. One command — nothing else to set up.

8 Tools

get_health_summary Overview · key metrics

get_health_summary(days: int) → {steps, hrv_sdnn_ms, resting_heart_rate_bpm, sleep_hours, workout_count}

Overview of key metrics across a date range.

Example prompt
"What's my health summary for the last 7 days?"
Return shape
{
  "steps": 8432,
  "hrv_sdnn_ms": 52.1,
  "resting_heart_rate_bpm": 58,
  "sleep_hours": 7.3,
  "workout_count": 4
}
get_sleep Sleep stages · per night

get_sleep(days: int) → [{date, duration_hours, rem_hours, core_hours, deep_hours, awake_hours, efficiency_pct}]

Per-night sleep stage breakdown.

Example prompt
"How was my sleep last week?"
Return shape
[{
  "date": "2026-06-17",
  "duration_hours": 7.5,
  "rem_hours": 1.8,
  "core_hours": 4.2,
  "deep_hours": 1.1,
  "awake_hours": 0.4,
  "efficiency_pct": 94.7
}]
get_hrv_trend HRV · trend delta

get_hrv_trend(days: int) → {daily: [{date, hrv_sdnn_ms}], trend_vs_prior_week_pct}

Daily HRV (SDNN) with trend delta vs prior period.

Example prompt
"Is my HRV improving?"
Return shape
{
  "daily": [
    {"date": "2026-06-17", "hrv_sdnn_ms": 54.2},
    {"date": "2026-06-16", "hrv_sdnn_ms": 49.8}
  ],
  "trend_vs_prior_week_pct": 6.3
}
get_daily_snapshot All metrics · single date

get_daily_snapshot(date: str) → {date, ...all metrics recorded that day}

All HealthKit samples recorded for a specific date.

Example prompt
"What does my health data look like for June 15?"
Return shape
{
  "date": "2026-06-15",
  "steps": 9241,
  "hrv_sdnn_ms": 51.4,
  "resting_hr_bpm": 57,
  "sleep_hours": 7.8,
  "active_calories": 612
}
get_workouts Workout log · type & intensity

get_workouts(days: int) → [{date, type, duration_min, distance_km, active_calories}]

Workout log with type and intensity metrics.

Example prompt
"How many workouts did I do this month?"
Return shape
[{
  "date": "2026-06-17",
  "type": "Running",
  "duration_min": 42,
  "distance_km": 6.8,
  "active_calories": 487
}]
query_metric Raw time series · any HKQuantityType

query_metric(metric_type: str, days: int) → [{timestamp, value, unit}]

Raw time series for any HKQuantityType identifier. See identifier table below.

Example prompt
"Show me my VO2 max readings for the last 90 days"
Return shape
[{
  "timestamp": "2026-06-17T07:14:22Z",
  "value": 48.3,
  "unit": "mL/kg/min"
}]
get_long_term_trend Monthly aggregates · multi-year

get_long_term_trend(metric_type: str, months: int) → [{month, avg_value, sample_count}]

Multi-year monthly aggregates. Automatically uses the summary data tier beyond 180 days for query efficiency.

Example prompt
"What's my HRV trend for the last 2 years?"
Return shape
[{
  "month": "2026-06",
  "avg_value": 51.8,
  "sample_count": 17
}]
get_coaching_brief Structured context · AI agents

get_coaching_brief() → {recovery_score, sleep_quality, training_load, recommendation}

Structured coaching context for AI agents. Suitable as a system prompt prefix or daily brief.

Example prompt
"Give me a training readiness brief"
Return shape
{
  "recovery_score": 78,
  "sleep_quality": "good",
  "training_load": "moderate",
  "recommendation": "Ready for intensity. HRV elevated vs baseline."
}

HKQuantityType Identifiers

Pass these strings as metric_type to query_metric or get_long_term_trend.

Identifier Metric
HKQuantityTypeIdentifierHeartRateVariabilitySDNN HRV
HKQuantityTypeIdentifierRestingHeartRate Resting HR
HKQuantityTypeIdentifierVO2Max VO2 max
HKQuantityTypeIdentifierStepCount Steps
HKQuantityTypeIdentifierActiveEnergyBurned Active calories
HKQuantityTypeIdentifierBodyMass Weight
HKQuantityTypeIdentifierOxygenSaturation Blood oxygen
Early Access

Connect your Apple Health data to Claude

Join the waitlist and get notified at App Store launch.

Join the waitlist