Skip to main content
Glama
Samsung Health Analytics MCP

Samsung Health Analytics MCP

by mo-debugs

Samsung Health Analytics MCP

Ask Claude about your Samsung Health data. Get the trends the Samsung Health app does not show you.

The Samsung Health app shows you today and this week. Your export holds months of data, but nothing in the app answers questions like these:

  • How has my sleep changed month by month this year?

  • Did my habits change after I moved, changed jobs or started training?

  • When in the day do I actually move?

  • What happens to my sleep and heart rate when I travel?

This repo loads your export into a local DuckDB database and gives Claude an MCP server to query it. Claude builds a one-page dashboard artifact first, then answers your questions.

What you get

  • Month-by-month trends for steps, active time, sleep, sleep score, deep sleep, sleep interruptions, sleeping heart rate and HRV.

  • Any two periods side by side (before/after a move, a new job, a training block), with effect sizes, so small noise is not reported as change.

  • Trips detected automatically from the timezone your phone reported. No location data needed. Each trip is compared with the 30 home days before it, and travel days are left out of the comparisons.

  • A 24-hour movement clock showing when in the day you walk.

  • A dashboard artifact with three actions for the next 30 days, written by Claude from your numbers.

Related MCP server: Apple Health Chat MCP

How it works

Samsung Health app
  | Settings > Download personal data
  v
export.zip ---> data/ (gitignored, stays on your machine)
                  |
                  v
        +------ dev container ------+
        |  ingest -> health.duckdb  |
        |  MCP server (stdio)       |
        +---------------------------+
                  ^  docker exec (.mcp.json)
                  |
            Claude Code
              |  1. ingest_export
              |  2. health-dashboard skill -> artifact
              v  3. your questions

Only aggregates (averages, counts, comparisons) reach the conversation. The raw export never leaves your machine, and the server opens the database read-only for queries.

Quick start

You need Docker and Claude Code.

  1. Export your data: Samsung Health app > profile > Settings > Download personal data. Copy the folder or zip to your computer.

  2. Clone and open Claude Code in the repo:

    git clone https://github.com/mo-debugs/samsung-health-analytics-mcp
    cd samsung-health-analytics-mcp
    claude
  3. Say: "Set up the health MCP." Claude builds the dev container (a few minutes the first time) and asks you to reconnect the server with /mcp.

  4. Say: "My export is at ~/Downloads/.zip." Claude copies it into data/, loads it and asks what you want to compare.

  5. Claude builds your dashboard. Then ask anything:

    • "Compare March with April."

    • "Which month did I sleep best, and what was different?"

    • "Show my unusual days for resting heart rate."

    • "How did my last trip affect my sleep?"

Refresh monthly: download a new export and say "Here is my new export, refresh my dashboard."

Without Docker

Install it as a Claude Code plugin instead (needs uv). Data is then stored in ~/.samsung-health/.

/plugin install samsung-health-analytics --marketplace mo-debugs/samsung-health-analytics-mcp

MCP tools

Tool

What it does

ingest_export

Load an export zip or folder (replaces the previous load)

set_periods

Save the two periods to compare

overview

Date range and data coverage per metric

monthly_trends

Monthly averages with month-over-month change

compare_periods

Two periods side by side, saved or ad hoc date ranges

trips

Trips from timezone changes, and the travel effect

hourly_profile, weekday_profile

When you move, by hour and weekday

sleep_timing

Bedtime, wake time, split nights, consistency

rolling_baseline

Days that were unusual for you (z-score vs your last 28 days)

detect_locations

Timeline of timezone runs, to spot moves

workouts

Exercise sessions by month and type

schema, run_sql

Read-only SQL for anything else

dashboard_payload, render_dashboard

Data for the report, and the rendered HTML

Notes and limits

  • Steps use Samsung's merged daily total (phone and watch combined), so they are not double counted.

  • Travel detection: a day counts as away when its timezone covers less than 35% of the surrounding 90 days. Daylight saving and permanent moves are handled. A trip longer than about a month starts to look like a move, so its first days may be counted as home.

  • Timezone is not location. Two countries in the same timezone look the same. Claude asks you to name your trips.

  • Samsung changes its export format between app versions. The ingester reads columns by name and skips files it cannot find. If something breaks, open an issue with the file name (never your data).

  • This is wellness data, not medical advice.

Development

uv sync
uv run pytest                                     # pipeline test on a synthetic export
uv run shealth-ingest path/to/export.zip          # CLI ingest
uv run shealth-dashboard --story story.json       # render the dashboard without Claude

Credits

Created by Mohammed Sarfarazuddin. If you use or build on this work, please credit it with a link back to this repository.

Feel free to connect on LinkedIn. Based in Riyadh? Feel free to reach out! I am on my quest to explore the best coffee place in Riyadh :)

License

MIT

Available Tools

16 tools
compare_periodsA

Compare two periods. Either names from set_periods (defaults: the first two), or ad hoc ranges a_range/b_range like "2025-03-01..2025-03-31" (period_a/period_b then become their labels). Returns mean/median/n per period, delta %, Cohen's d and a plain verdict per metric. Travel days excluded by default.

Inputs: a_range, b_range, metrics, period_a, +2 more.

dashboard_payloadA

Everything the dashboard renders, including precomputed signals and trips. Read this before writing the story.

Inputs: no named parameters.

detect_locationsB

Timeline of contiguous UTC-offset runs: homes and trips. Use it to suggest periods (e.g. a move).

Inputs: min_days. Returns: result

hourly_profileC

Average steps for each hour of the day (0-23), per period. Shows when you move.

Inputs: period, home_only.

ingest_exportA

Load a Samsung Health export (.zip or extracted folder) into the local database, replacing the old one. Takes about 10 seconds. Re-run whenever the user downloads a fresh export.

Inputs: path (required).

overviewC

Date range, data coverage per metric, available metrics and the periods being compared.

Inputs: no named parameters.

render_dashboardA

Render the single-file dashboard with the story you wrote from the payload. actions: 3 items of {title, detail, metric, target}, each grounded in a payload number. headline: one sentence, the most important finding. subtitle: one line of context. callouts: labels on the 24h clock, e.g. [{"hour": 6, "text": "Morning run"}], only for causes the user confirmed. travel_note: one or two sentences about the user's travel, from trips. trip_labels: [{"start": "2025-08-02", "label": "Lisbon"}] keyed by trip start date; only labels the user confirmed or that the timezone makes unambiguous. Returns the file path; set return_html=True when the client cannot read local files (e.g. Claude Desktop).

Inputs: actions (required), callouts, headline, subtitle, +3 more.

rolling_baselineB

Each day's value against your own trailing baseline, with a z-score. |z| > 2 is unusual for you.

Inputs: metric, window_days. Returns: result

run_sqlB

Run a read-only DuckDB query. Main table: daily. Others: hourly_steps, exercise, sleep_sessions, weight, day_tz, day_home.

Inputs: query (required), limit. Returns: result

schemaA

Tables and columns available to run_sql.

Inputs: no named parameters.

set_periodsA

Save the periods to compare, e.g. [{"name": "Before", "start": "2025-01-01", "end": "2025-06-30"}, {"name": "After", "start": "2025-07-01"}]. end empty means today. Optional tz_offsets (["+01:00"]) overrides automatic travel detection for that period. Pass [] to go back to the 90-day default.

Inputs: periods (required).

sleep_timingC

Bedtime, wake time, sleep hours, split nights and bedtime consistency (std dev in minutes) per period.

Inputs: home_only.

tripsB

Trips detected from the phone's timezone (no location data needed), each compared with the 30 home days before it, plus the overall travel effect on steps, sleep and heart rate.

Inputs: min_days.

weekday_profileC

Average of a metric per weekday (Mon..Sun), per period. Useful for weekend effects (Sat/Sun vs Fri/Sat).

Inputs: metric, home_only.

workoutsC

Recorded exercise sessions grouped by month, period and type.

Inputs: end, start. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 16 tools

    Disambiguation4/5

    Each tool targets a distinct analysis surface (trends, periods, trips, sleep, workouts, SQL). There is mild overlap between overview and dashboard_payload (both summarize the dataset), and between trips and detect_locations (both derive travel), but descriptions make the split between summary/payload and analysis/raw-timeline reasonably clear.

    Naming Consistency3/5

    All names are snake_case and readable, but the convention is mixed: several are verb_noun (ingest_export, set_periods, render_dashboard, compare_periods, run_sql) while others are bare nouns (overview, trips, workouts, schema, sleep_timing). The inconsistency is minor but visible across 16 tools.

    Tool Count4/5

    16 tools is just over the comfortable band but justified by a genuinely broad analytics domain (ingestion, overview, trends, profiles, comparisons, travel, SQL escape hatch, dashboard). No single tool looks trivially redundant, though the overview/dashboard_payload pair could likely merge.

    Completeness4/5

    Coverage is strong: ingestion, schema inspection, raw SQL, period definition, trends, comparisons, profiles, sleep, baselines, trips, workouts, and dashboard output. Minor gaps exist around exporting analysis results or persistent saved analyses, but agents can work around them via run_sql.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude Desktop to access and analyze Garmin wearable health data including sleep, HRV, Body Battery, and activity metrics. Users can query their health trends, track recovery, and generate interactive HTML dashboards using natural language.
      9
      7
      MIT
    • A
      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
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides Claude with real-time access to local health data including sleep, recovery, strain, and workouts from WHOOP and Apple Health, enabling informed context-aware interactions.
      6
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude clients to read Oura Ring sleep, heart rate, readiness, and activity data; log, delete, and query home glucose, ketone, weight, blood pressure, and nutrition readings; and ingest Apple Health data via Health Auto Export.
      27 npm
      MIT