Skip to main content
Glama

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

Open Wearables

sleep, weight, activity, recovery, workouts, health scores, time series

OW_API_KEY, OW_USER_ID, OW_BASE_URL

strong-data

lifting sessions, sets, volume, records, yearly progress

STRONG_API_URL, STRONG_API_TOKEN

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 sync

Dates: 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.server

Streamable 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_TOKENS is name:sha256(token) pairs, one per consumer; the single-consumer MCP_BEARER_TOKEN alias is hashed to default. HTTP mode fails closed when both are empty.

  • The MCP endpoint is MCP_PATH (default /mcp).

  • GET /healthz is the only anonymous route; any other method on it is 405.

  • 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

get_weight_trend, get_sleep_summary, get_activity_summary, get_recovery_summary, get_workouts, get_health_scores, get_timeseries

strong-data

get_lifting_summary, get_lifting_trend, get_lifting_breakdown, get_lifting_sessions

Composite

get_overview, get_daily_checkin, get_sleep_training_correlation

Any source

get_status, refresh_cache

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 above

planning/ 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 tools
get_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

    B3.2/5.0

    Scored across 9 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      8
      100 PyPI
      1
      GPL 3.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      4
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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 PyPI
      MIT