Health MCP
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., "@Health MCP Show me my sleep, activity, and recovery for this week."
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.
Health MCP
A small Model Context Protocol server for personal health data. It exposes stats-first tools over read-only sources and is designed to run locally (stdio) or as a container behind a reverse proxy (streamable HTTP with bearer auth).
Data sources
Source | Data | Access |
sleep, weight, activity, recovery, workouts, health scores, time series |
| |
lifting sessions, sets, volume, records, yearly progress |
|
Every source is optional: enable it by setting its credentials, or restrict the
set explicitly with SOURCES. With neither configured the server refuses to
start; with one configured the other's tools are simply not registered and
composites report it in missing. Enabling a source is a new module under
sources/ only.
There is no database access and no lifting CSV parsing in the server —
strong-data imports the Strong export, and this server only reads its API.
Related MCP server: apple-health-shortcuts-mcp
Setup
cp .env.example .env # fill in whichever sources you have
uv syncDates: every date crossing the tool boundary is YYYY-MM-DD and is an
installation-local calendar date (TZ, default Europe/Stockholm). Open
Wearables UTC timestamps are converted to TZ before truncation, never
formatted from UTC.
Run
Local stdio, for an MCP client such as pi or OpenCode:
uv run python -m health_mcp.serverStreamable HTTP, for the container or a remote client:
MCP_TRANSPORT=http \
MCP_BEARER_TOKENS="pi:$(printf %s "$TOKEN" | sha256sum | cut -d' ' -f1)" \
uv run python -m health_mcp.server(uvicorn health_mcp.asgi:app --host 0.0.0.0 --port 8000 --workers 1 is the
equivalent direct entrypoint; MCP_TRANSPORT=http makes python -m health_mcp.server use it, honouring MCP_HOST/MCP_PORT/MCP_PATH.)
MCP_BEARER_TOKENSisname:sha256(token)pairs, one per consumer; the single-consumerMCP_BEARER_TOKENalias is hashed todefault. HTTP mode fails closed when both are empty.The MCP endpoint is
MCP_PATH(default/mcp).GET /healthzis the only anonymous route; any other method on it is405.One process, one cache. Do not run multiple workers: the cache has no cross-process locking.
Tools
All range tools take start_date/end_date as YYYY-MM-DD. They return
aggregates by default and include a capped series only with include_series=true
(plus total_points and truncated). get_timeseries takes ISO timestamps and
a resolution level instead.
Source | Tools |
Open Wearables |
|
|
|
Composite |
|
Any source |
|
The composite tools need both sources; without one they return the partial
answer plus "missing": [...]. get_sleep_training_correlation defaults to
lag_days=1 (lifting volume on day D vs sleep on D+1) and always reports n,
r, lag_days, definition and period.
Generate the exact list for a deployment (this is the only sanctioned source for
the README table and for the ZeroClaw auto_approve list):
uv run python -m health_mcp.tools --names --all-sources
uv run python -m health_mcp.tools --names --agent health --prefix health__Container
docker build -t health-mcp:dev .The image runs as 1000:100, needs PROFILE_DIR and CACHE_DIR mounts, and
exposes port 8000. It disables FastMCP's update check and banner
(FASTMCP_CHECK_FOR_UPDATES=off), so the service makes no egress beyond its two
upstream APIs. The build applies Debian point-release fixes and drops pip and the
ensurepip wheels, because the server installs and runs through uv alone. Pin the
base images by digest at deploy time via
--build-arg PYTHON_IMAGE=... --build-arg UV_IMAGE=.... The compose stack,
Caddy host and AdGuard rewrite live in the olympus-stacks repo, not here.
Continuous integration and releases
.github/workflows/ci.yml runs the full check on every push, pull request, weekly
schedule and manual dispatch: lockfile, lint, formatting, types, tests, the PII audit,
a dependency audit, workflow linting, plus a production image build whose container is
started with synthetic configuration to verify the /healthz and bearer-auth contract
and scanned for known vulnerabilities. dependency-review blocks new high-severity
dependencies, zizmor audits the workflows and Scorecard publishes the OpenSSF result.
main is protected: squash-only pull requests, resolved review threads and the
Checks (Linux), Container (Linux) and Dependency review checks; X.Y.Z tags are
protected against moving or deletion. Dependabot updates the Python, action and Docker
dependencies, and policy-compliant patch updates merge automatically.
.github/workflows/release.yml publishes a release: pushing a bare X.Y.Z tag on a
tested main commit builds linux/amd64 and linux/arm64, checks both images,
publishes the multi-platform index to ghcr.io/<owner>/health-mcp as <version> and
latest, and attests provenance and a per-platform SBOM before creating the GitHub
Release. GHCR package visibility is independent of the repository; the first release
may need the package set to public in its settings, and the latest tag only moves for
the current stable release.
Development
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run pyright
bash scripts/pii_audit.sh # PII / secret scan
bash scripts/check.sh # all of the aboveplanning/ is private working material and is not tracked. Tests use synthetic
payloads only; never commit .env, caches or real health data. SECURITY.md
says what counts as personal data and how to report a vulnerability privately;
CONTRIBUTING.md covers the rules, the release process and the
contributor agreement.
License
PolyForm Noncommercial License 1.0.0 — source-available, not OSI open source. Noncommercial use is permitted; commercial use is not granted. See LICENSE.
Available Tools
9 toolsget_daily_checkinGet Daily CheckinC
Single-day rollup: weight, sleep, workout minutes, recovery and lifting.
Inputs: date (required). Returns: object
get_lifting_breakdownGet Lifting BreakdownB
Volume and session counts split by weekday, program, muscle or exercise.
Inputs: end_date (required), start_date (required), limit, program, +1 more. Returns: object
get_lifting_sessionsGet Lifting SessionsC
Paginated lifting sessions; include_sets expands up to 10 sessions.
Inputs: end_date (required), start_date (required), sort, limit, +6 more. Returns: object
get_lifting_summaryGet Lifting SummaryC
Lifting totals, top exercises, muscle balance and weekly volume.
Inputs: end_date (required), start_date (required), top_n. Returns: object
get_lifting_trendGet Lifting TrendB
One lifting metric over time. Week buckets also carry a 4-week moving average.
Inputs: end_date (required), start_date (required), bucket, metric, +3 more. Returns: object
get_overviewGet OverviewC
One-call overview: weight, sleep, activity, recovery, workouts, lifting, consistency.
Inputs: end_date (required), start_date (required). Returns: object
get_sleep_training_correlationGet Sleep Training CorrelationC
Correlation between lifting volume and sleep, with n, r, lag and period.
Inputs: end_date (required), start_date (required), lag_days. Returns: object
get_statusGet StatusB
Server status: today, enabled sources, reachability, cache age and profile presence.
Inputs: no named parameters. Returns: object
refresh_cacheRefresh CacheA
Clear cached API responses. The next query re-fetches.
Inputs: source. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The four lifting tools (sessions, summary, trend, breakdown) overlap conceptually: summary and breakdown both report volume by muscle/exercise, and trend vs summary can be confused for time-based questions. get_overview vs get_daily_checkin is also a close pair (all-metrics rollup vs single-day rollup), though the descriptions do draw the line. The rest (status, correlation, refresh_cache) are clearly distinct.
Every tool uses a consistent snake_case verb_noun pattern (get_*), with refresh_cache as the only non-get verb, which correctly signals its mutating side effect. Prefixing the lifting family with get_lifting_* makes the grouping obvious.
Nine tools is well within the sweet spot and each earns its place: one status/probe, one cache-control, and seven analytics/query tools covering sessions, aggregates, trends, breakdowns, correlations and rollups. Nothing looks like padding.
The surface is read-only: there is no way to write or log a session, meal or check-in, and raw weight/sleep/activity time series are only reachable aggregated through get_overview or get_daily_checkin. Lifting is covered thoroughly (sessions, summary, trend, breakdown), but sleep gets only a correlation tool and nutrition is absent entirely, so agents will hit dead ends for raw-series or write workflows.
Maintenance
Related MCP Connectors
Read-only Apple Health data synced from your iPhone: sleep, heart rate, HRV, workouts and trends.
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
Read sleep, readiness, activity, stress, heart rate and workouts from the Oura Ring.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides read-only access to Withings health metrics including body composition, sleep, workouts, and ECG data with local SQLite caching and trend analysis. Features incremental synchronization, automatic OAuth token refresh, and supports all 200+ Withings measurement types for comprehensive health tracking.8100 PyPI1GPL 3.0
- AlicenseNot gradedqualityNot gradedmaintenanceExposes Apple Health data as three read-only MCP tools (now, detail, trends) for AI to query health metrics, sleep, and trends via HTTP.MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to query locally computed recovery, strain, sleep, workout, and heart-rate data from a personal SQLite database, with tools for daily and sleep summaries, workout details, heart-rate buckets, schema inspection, reports, sync, and read-only SQL.48MIT
- AlicenseNot gradedqualityCmaintenanceProvides read-only access to Oura Ring health and activity data, including sleep, readiness, activity, stress, SpO2, resilience, workouts, sessions, and heart rate via the Oura API v2.18 PyPIMIT