Samsung Health Analytics MCP
This MCP server loads a Samsung Health export into a local DuckDB database and gives Claude tools to analyze trends, comparisons, travel, activity/sleep patterns, and build a dashboard.
Ingest a Samsung Health export from a zip or folder, replacing the previous database.
Save comparison periods and get an overview of date range, metrics, coverage, and active periods.
Compute monthly trends with month-over-month changes and compare two periods with means, medians, deltas, Cohen’s d, and verdicts.
Detect trips from timezone changes, estimate travel effects, and show location/timezone timelines.
Analyze hourly step patterns, weekday profiles, sleep timing/consistency, and unusual days via rolling z-scores.
Summarize workouts by month, period, and type.
Inspect the database schema and run read-only DuckDB SQL against tables like
daily,hourly_steps,exercise,sleep_sessions,weight,day_tz, andday_home.Generate a dashboard payload and render a single-file HTML dashboard with headline, travel note, callouts, and grounded actions.
Loads Samsung Health export data into a local database and provides tools to analyze health metrics such as sleep, steps, heart rate, HRV, workouts, trips, and daily activity patterns. Supports monthly trends, period comparisons, unusual-day detection, travel effects, and dashboard generation from Samsung Health data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Samsung Health Analytics MCP Compare my sleep in March vs April and tell me what changed"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 questionsOnly 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.
Export your data: Samsung Health app > profile > Settings > Download personal data. Copy the folder or zip to your computer.
Clone and open Claude Code in the repo:
git clone https://github.com/mo-debugs/samsung-health-analytics-mcp cd samsung-health-analytics-mcp claudeSay: "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.Say: "My export is at ~/Downloads/.zip." Claude copies it into
data/, loads it and asks what you want to compare.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-mcpMCP tools
Tool | What it does |
| Load an export zip or folder (replaces the previous load) |
| Save the two periods to compare |
| Date range and data coverage per metric |
| Monthly averages with month-over-month change |
| Two periods side by side, saved or ad hoc date ranges |
| Trips from timezone changes, and the travel effect |
| When you move, by hour and weekday |
| Bedtime, wake time, split nights, consistency |
| Days that were unusual for you (z-score vs your last 28 days) |
| Timeline of timezone runs, to spot moves |
| Exercise sessions by month and type |
| Read-only SQL for anything else |
| 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 ClaudeCredits
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
Available Tools
16 toolscompare_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).
monthly_trendsB
Monthly averages per metric with month-over-month % change (mom_pct). Dates are YYYY-MM-DD. home_only=True drops travel days. Metrics default to the core set; see overview() for all keys.
Inputs: end, start, metrics, home_only. Returns: result
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
Scored across 16 tools
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.
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.
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.
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
Ask Claude, ChatGPT or Cursor about your Apple Health data: workouts, sleep, food. Read-only.
Your lab results and health record in Claude: trends, retests, meds, conditions and symptoms.
Apple Health training load, recovery, HRV and workout detail for Claude, ChatGPT and any MCP client.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.97MIT
- AlicenseBqualityDmaintenanceEnables 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.62MIT
- AlicenseAqualityDmaintenanceProvides 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.61MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 npmMIT