Google Health Mcp

Google Health MCP

Read user-authorized Google Health API v4 data — Fitbit, Pixel Watch and partners — locally via OAuth. Beta.
Local-first MCP server — tokens never leave your machine.

[npm version] [GitHub release] [npm downloads] [CI] [License MIT] [Site]

[GitHub stars] [Built for MCP] [Verified release index] [Hermes one-command setup] [Google Health]

⚡ One-command install with Delx Wellness for Hermes: npx -y delx-wellness-hermes setup — preconfigures this connector and the other 8 in a dedicated Hermes profile.

Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.

What's new in 0.7.3 (2026-08-03): headless OAuth (auth --manual) for SSH / containers / WSL · real-account rollup/filter fixes from external testers · opt-in clinical scopes for ECG/IRN · pins live in Hermes/living-body. Full notes in CHANGELOG.md.

Highest-leverage contribution — real-account coverage

If you have Fitbit, Pixel Watch, Android health data or Google Health API v4 access, the most useful help is a redacted coverage report:

npx -y google-health-mcp-unofficial coverage --live --json

Review the output, remove anything you do not want public, then post the report on issue #2 (or a new issue). The timed proof loop on #21 closed 1/2 — see docs/proof-loop-status.md. The command is read-only and is designed to omit OAuth secrets, local paths and raw health measurements. A static preflight is available before OAuth with coverage --json.

Other ways to help (no account required)

HTTP (v2 stateless)

Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:

npx -y google-health-mcp-unofficial --http# GET  http://127.0.0.1:3000/health# POST http://127.0.0.1:3000/mcp   (sessionless)

Env: GOOGLE_HEALTH_MCP_HOST, GOOGLE_HEALTH_MCP_PORT, GOOGLE_HEALTH_MCP_TRANSPORT=http.

Google Health MCP

Local-first MCP server that gives your AI agent user-authorized Google Health API v4 data — Fitbit, Pixel Watch and partners — over OAuth.

• Install one connector — npx -y google-health-mcp-unofficial setup
• Run it in Claude · Cursor · ChatGPT · Hermes · OpenClaw — see the client examples.
• Local-first — your tokens never leave your machine (privacy).
• Which connector should I use? — see the front-door guide.

Beta status: Google Health API v4 is live for builders but still evolving. Google's release notes show scope and data-type changes continuing after launch, so this connector stays in early beta and points testers to safe read-only validation paths before public production use.

Unofficial project. Not affiliated with, endorsed by or supported by Google, Fitbit or Alphabet. Not a medical device. Not medical advice.

Why this exists

Google Health API is the successor to Fitbit Web API: new OAuth, new base URL, v4 endpoint schema, standardized data types, reconciled streams and rollups.

This MCP gives agents a clean way to discover the API, check setup, authenticate locally and query data without pasting tokens into prompts or agent configs.

Quickstart in 60 seconds

Create a Google Cloud OAuth client, enable the Google Health API, and add the redirect http://127.0.0.1:3000/callback. Then:

npx -y google-health-mcp-unofficial setup --scope-preset full   # writes local confignpx -y google-health-mcp-unofficial auth                        # OAuth, tokens saved locallynpx -y google-health-mcp-unofficial doctor                      # verifies you're ready

doctor --live calls safe Google Health identity/profile/settings endpoints after auth to prove the API is reachable — the connection proof for this beta. That does not prove Claude Desktop can invoke tools: Desktop validates outputSchema as JSON Schema 2020-12. Use [email protected]+ (see #23). Full install details (scope presets, MFA, recovery) are in the Install section below.

Try it with your agent

Three things to ask first, based on tools this connector actually ships:

Use google_health_connection_status to check setup, then rungoogle_health_data_inventory. Tell me which Google Health domainsand scopes I have authorized.

Call google_health_daily_summary for today, then google_health_weekly_summary.Separate observed data from suggestions and stay non-medical.

Run google_health_privacy_audit, then summarize exactly what is storedlocally and what would be sent to Google on the next call.

Tools

Start here:

• google_health_connection_status — local config, token, scope and client readiness
• google_health_data_inventory — supported domains, scopes, data type naming and agent flow
• google_health_data_type_coverage — static coverage plan, or explicit live read-only validation for issue #21
• google_health_daily_summary — daily beta summary from rollups and reconciled streams
• google_health_weekly_summary — weekly beta review
• google_health_privacy_audit — what is stored locally and what is sent to Google

The full tool catalog — Google Health API methods, agent manifest, diagnostics and data-type naming notes (kebab-case endpoints, snake_case filters, source families) — lives in docs/tools.md.

Privacy & what runs offline

• OAuth tokens are stored locally at ~/.google-health-mcp/tokens.json with 0600 permissions.

• Secrets can live in ~/.google-health-mcp/config.json or GOOGLE_HEALTH_* environment variables.

• Tools never return access tokens, refresh tokens or client secrets.

• GOOGLE_HEALTH_PRIVACY_MODE=structured is the default; raw mode is explicit and should be used only for debugging or deep analysis. An agent asking for privacy_mode=raw is refused unless it passes explicit_user_intent=true; setting GOOGLE_HEALTH_PRIVACY_MODE=raw yourself is your own call and needs no per-call intent.

• Structured mode preserves complete upstream physiological fields and future v4 additions while removing identity, location and secret-bearing values.

• "Location redaction" means a concrete key list, not a slogan. Coordinate-bearing leaf keys, always dropped in structured and summary (matched ignoring case, _ and -, so latitude_e7 and latitudeE7 are the same key):

  startLatitude, startLongitude, start_latlng, endLatitude, endLongitude, end_latlng, latitude, longitude, lat, lon, lng, latlng, coordinates, coordinate, gps, gpx, geoPolylineDTO, map, polyline, summary_polyline, activities-tracker-gps, latitudeE7, longitudeE7, latE7, lngE7, lonE7, startLatitudeE7, startLongitudeE7, endLatitudeE7, endLongitudeE7, lat_deg, lng_deg, lon_deg, latitudeDegrees, longitudeDegrees

  Location container keys, dropped as a whole object — with their address/city/placeId siblings and any coordinate spelling this list never anticipated — whenever they hold a place record (an object, or an array containing objects). A container holding only scalars is a label, not a place, and survives: location: ["gym", "home"] stays, location: { latitudeE7: … } does not.

  location, locations, geoLocation, geoLocations, geo, geoJson, route, routes, position, positions, waypoint, waypoints, trackPoint, trackPoints, placeVisit

  google_health_privacy_audit returns both live lists in gps_redacted_keys and gps_redacted_container_keys, and gps_redaction_default is measured at call time by pushing a synthetic record through both non-raw modes and scanning the output by key and by coordinate value — it is not a hardcoded true. npm run test:redaction-docs fails the build if these two blocks stop matching the code, so the published promise cannot drift from the enforcement list again. Google Health API v4 does not currently document a location/route data type, so this is a forward-compatible guard rather than a patch for an observed leak.

• Limits of that promise, stated instead of implied. Every line below is proved by a behavioural test (npm run test:declared-limits) that fails if the behaviour changes; a line marked NOT VERIFIED is a statement no test backs, labelled instead of left to read as a guarantee. A limit written here without a test fails the build:

  • default_mode_is_structured — with no privacy_mode argument and no GOOGLE_HEALTH_PRIVACY_MODE, every read runs in structured.
  • raw_requires_explicit_user_intent — an agent asking for privacy_mode=raw is refused with USER_ACTION_REQUIRED unless it also passes explicit_user_intent=true.
  • local_raw_default_needs_no_per_call_intent — GOOGLE_HEALTH_PRIVACY_MODE=raw in your own config or environment is honoured on every call with no per-call intent; the gate is about agent escalation, not about the machine owner.
  • raw_is_an_unfiltered_passthrough — raw returns the upstream payload unchanged; redaction is a property of structured and summary, never of raw.
  • structured_drops_identity_and_secret_keys — tokens, authorization, e-mail, names and avatars are dropped at any depth in structured, while physiology and provenance survive.
  • summary_is_never_less_restrictive_than_structured — summary strips first and summarizes after, so nothing structured drops can reappear in summary.
  • summary_flattens_numeric_leaves_to_depth_2 — summary promotes numeric leaves down to depth 2 of the data-type payload into value; anything deeper is not reported at all.
  • summary_promotes_unlisted_coordinate_keys — a coordinate key outside the lists above is promoted by summary, not hidden. The key list is the boundary, not the mode.
  • altitude_and_elevation_are_not_location — altitude is an official v4 data type (activity_and_fitness) and survives redaction, as does elevation; an altitude alone does not localize a user.
  • altitude_inside_a_place_container_is_dropped — the same altitude inside a redacted location container dies with the container.
  • location_guard_never_observed_upstream — NOT VERIFIED: Google Health API v4 documents no location/route data type, so no test here has ever seen a real Google payload carrying coordinates. The key list is a forward-compatible guard derived from Google's own encodings, not a measured fix for an observed leak.

• Daily rollups use validated civil YYYY-MM-DD ranges; general rollups preserve exact timezone-aware ISO date-times. Invalid or reversed ranges fail before HTTP.

• "today" in summaries and daily rollups resolves in the timezone argument, else the wellness profile's timezone, else UTC. An invalid IANA timezone is rejected.

• support --redacted prints a copy-paste support bundle for GitHub issues without tokens, secrets, local paths or health measurements.

• support --feedback --json prints an anonymous setup-feedback bundle for beta testers and MCP client reports.

• coverage --live --json prints only redacted data-type status and point-count buckets; it never includes raw Google Health payloads.

Authorization model & trust boundary

Google OAuth controls which Google account and health scopes this connector can access. It does not authorize individual MCP callers or tools. The intended deployment is one local user running one trusted MCP host; callers that can reach the same process share its tool catalog and local OAuth grant.

There is currently no per-user, per-agent, API-key or per-tool RBAC layer. The optional HTTP transport binds to 127.0.0.1 by default and must not be exposed publicly without standards-compliant MCP authentication, isolated per-user Google credentials and an explicit authorization policy. See the full authorization model.

See the full agent demo →

Want to see an agent actually reason over this connector alongside the rest of the stack? The shared, reproducible demo answers the anchor question "Should I train hard today?":

npx -y delx-living-body demo

delx-living-body composes whatever connectors it detects locally with rule-based (offline) synthesis — readiness-first and non-medical. For this connector specifically, npx -y google-health-mcp-unofficial doctor --live is the local proof that your Google Health auth is wired correctly.

Beta Testers Wanted

The highest-leverage contribution right now is real setup feedback from Fitbit, Pixel Watch, Android and Google Health API v4 users.

If you can test with a real account:

• Run npx -y google-health-mcp-unofficial doctor and confirm the OAuth flow is clear.
• Run npx -y google-health-mcp-unofficial support --feedback --json and paste the anonymous bundle into issue #4.
• Run npx -y google-health-mcp-unofficial coverage --json for the static coverage plan.
• After OAuth, run npx -y google-health-mcp-unofficial coverage --live --json and paste the reviewed, redacted report into issue #2.
• Try google_health_connection_status, google_health_data_inventory and google_health_daily_summary from your MCP client.
• Open an issue for missing data types, confusing setup steps, client-specific friction or privacy concerns.
• Do not paste OAuth tokens, client secrets, local paths or personal health measurements into public issues.

Useful links:

• Beta testers wanted
• Proof loop status (honest 1/2)
• Beta testers / new coverage
• MCP client setup feedback
• Beta feedback guide
• Data coverage harness
• Anonymous setup feedback
• Demo
• Discovery kit

Install

Create a Google Cloud OAuth client, enable the Google Health API, and add the local redirect:

http://127.0.0.1:3000/callback

Then run:

npx -y google-health-mcp-unofficial setup --scope-preset fullnpx -y google-health-mcp-unofficial authnpx -y google-health-mcp-unofficial doctor

Headless hosts (servers, SSH, containers, WSL)

auth normally opens a browser and catches the redirect on 127.0.0.1. On a host with no browser that cannot work. When it detects a headless host — SSH, or no DISPLAY / WAYLAND_DISPLAY — it switches to pasting the redirect back in:

npx -y google-health-mcp-unofficial auth --manual

Non-interactive provisioning:

npx -y google-health-mcp-unofficial auth --print-urlnpx -y google-health-mcp-unofficial auth --code "http://127.0.0.1:3000/callback?code=..."

See docs/oauth.md for --local-callback, SSH tunnel notes, and GOOGLE_HEALTH_HEADLESS.

Scope presets keep OAuth consent easier to reason about — basic, activity, sleep and full. The full preset list, the exact read-only scope URLs and the OAuth endpoints live in docs/oauth.md.

If setup gets stuck:

npx -y google-health-mcp-unofficial doctor --fix       # repairs local config/token permissions (chmod 600 where supported)npx -y google-health-mcp-unofficial doctor --live      # calls safe identity/profile/settings endpoints to prove the API is reachablenpx -y google-health-mcp-unofficial coverage --live --json # redacted read-only data-type coverage for issue #21npx -y google-health-mcp-unofficial support --redacted # copy-paste support bundle, no tokens/secrets/measurementsnpx -y google-health-mcp-unofficial support --feedback --json # anonymous setup feedback for issue #4

Standalone MCP config:

{  "mcpServers": {    "google_health": {      "command": "npx",      "args": ["-y", "google-health-mcp-unofficial"]    }  }}

Hermes

npx -y google-health-mcp-unofficial setup --client hermes --no-authnpx -y google-health-mcp-unofficial authnpx -y google-health-mcp-unofficial doctor --client hermes --fixnpx -y google-health-mcp-unofficial doctor --client hermes --livehermes mcp test google_health

After config changes, use /reload-mcp or hermes mcp test google_health. Do not restart the gateway for normal data access.

Development

git clone https://github.com/davidmosiah/google-health-mcp.gitcd google-health-mcpnpm installnpm test

Links

• Changelog · Contributing · Security · Authorization model
• Google Health API: https://developers.google.com/health
• Release notes: https://developers.google.com/health/release-notes
• REST reference: https://developers.google.com/health/reference/rest
• Scopes: https://developers.google.com/health/scopes
• Data types: https://developers.google.com/health/data-types
• Migration guide: https://developers.google.com/health/migration
• Delx Wellness registry: https://github.com/davidmosiah/delx-wellness

See also

The full Delx Wellness connector library:

One-command setup for Hermes — preconfigures every connector above plus wellness skills + onboarding: delx-wellness-hermes.

📧 Contact & Support

• 📨 [email protected] — general questions, integration help, partnerships
• 🐛 Bug reports / feature requests — GitHub Issues
• 🐦 Updates — @delx369 on X
• 🌐 Site — wellness.delx.ai

License

MIT - see LICENSE. Code of Conduct.

Agent-ready yardstick: mcp-scorecard — aim ≥90 on CI.

Skill or MCP

Same package, two doors. MCP registers tools on stdio/HTTP. The skill can drive the same tools through the CLI when the client has no MCP:

npx -y google-health-mcp-unofficial call google_health_connection_status --json '{}'

Copy skill/SKILL.md into your agent skills dir.

Release migration

Before upgrading to 0.8.0, review the compatibility and migration notes.