io.github.BerkKilicoglu/google-health-fitbit-mcp

An MCP server that runs locally and hands your AI agent your own Google Health API data — from Fitbit trackers, Pixel Watch and supported partner sources — through OAuth.

• Install in one command — npx -y google-health-fitbit-mcp setup
• Run it in Claude Desktop · Claude Code · Cursor · Windsurf · Hermes · OpenClaw — see client examples.
• On your machine — OAuth tokens are stored locally with 0600 permissions and are never returned by any tool (privacy).
• Read-only by default — every shipped data tool is a read. Writes are a gated, opt-in, dry-run-first design that is not enabled.

Beta status: Google Health API is available to developers but the surface is still moving. Because Google's release notes keep listing scope and data-type changes after launch, this connector remains in beta and steers testers toward safe read-only validation before any production use.

Independent, community-built connector — no affiliation with, endorsement from or support by Google, Fitbit or Alphabet. Not a medical device or medical advice; treat the data as trend context only.

⚡ Quick Connect

Prerequisite: a Google Cloud OAuth client (type: Desktop) with the Google Health API enabled and the redirect http://127.0.0.1:3000/callback registered — details in Install.

Step 1 — Install & authorize (once):

npx -y google-health-fitbit-mcp setup     # guided: Google Cloud OAuth client + scopes
npx -y google-health-fitbit-mcp auth      # browser OAuth — tokens stay on your machine
npx -y google-health-fitbit-mcp checkup   # ✓ verifies everything is ready

Step 2 — Connect your app:

claude mcp add google-health -- npx -y google-health-fitbit-mcp

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

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

npx -y google-health-fitbit-mcp setup --client hermes   # writes the Hermes config for you

Step 3 — Test it. Ask your agent:

Run google_health_connection_status and tell me if I'm connected.

Why this exists

The Google Health API is the successor to the Fitbit Web API: new OAuth, new base URL (https://health.googleapis.com), a streamlined endpoint schema, standardized kebab-case data types, reconciled cross-source streams and daily/physical-time rollups.

It gives agents a clean path to explore the API, verify their setup, sign in locally and pull data — with no need to paste tokens into prompts or agent configs.

Try it with your agent

Three good opening prompts, built around tools this connector genuinely ships:

Check my setup with google_health_connection_status, then call
google_health_data_inventory and tell me which Google Health
domains and scopes I've granted.

Pull today's google_health_daily_summary, then google_health_weekly_summary.
Keep observed data separate from any suggestions, and stay non-medical.

List my paired devices with google_health_list_paired_devices and tell me
which device is producing my sleep and heart-rate data.

Tools

29 tools, all read-only except the two explicitly gated local-profile/auth actions noted below.

Start here

Data reads (Google Health API)

Summaries & wellness context

Auth, diagnostics & metadata

google_health_get_auth_url · google_health_exchange_code (gated: requires explicit user intent) · google_health_revoke_access (gated + destructive: disconnects Google Health) · google_health_privacy_audit · google_health_cache_status · google_health_data_type_coverage · google_health_capabilities · google_health_agent_manifest · google_health_onboarding · google_health_profile_get · google_health_profile_update (local file only, requires explicit_user_intent=true)

Resources & prompts

MCP resources: google-health://agent-manifest, google-health://capabilities, google-health://inventory, google-health://latest/steps, google-health://profile, google-health://summary/daily, google-health://summary/weekly.

MCP prompts: google_health_daily_checkin, google_health_weekly_review, google_health_data_type_investigation.

Data types

39 data types from the official Google Health table, including steps, sleep, heart-rate, heart-rate-variability, daily-resting-heart-rate, active-zone-minutes, distance, total-calories, weight, body-fat, blood-glucose, oxygen-saturation, vo2-max, electrocardiogram, irregular-rhythm-notification, exercise, floors, swim-lengths-data, nutrition-log and hydration-log.

Naming rules agents need:

• Endpoints use kebab-case data types: steps, daily-resting-heart-rate.
• Filters use snake_case field paths: sleep.interval.civil_start_time, heart_rate.sample_time.physical_time.
• Source families: all-sources, google-wearables, google-sources.

Call google_health_list_data_types for the full catalog with units, scopes and which verbs (list/reconcile/rollup) each type supports.

Privacy & what runs offline

• OAuth tokens live on disk at ~/.google-health-mcp/tokens.json, locked down to 0600 permissions.
• Client secrets go in ~/.google-health-mcp/config.json or the GOOGLE_HEALTH_* environment variables.
• No tool ever hands back an access token, refresh token or client secret; error output is redacted too.
• The default privacy mode is GOOGLE_HEALTH_PRIVACY_MODE=structured; summary strips identifiers further, and raw is an explicit opt-in for debugging.
• GPS/route data is treated as sensitive and redacted unless explicitly requested.
• support prints a copy-paste support bundle for GitHub issues — always redacted, never contains tokens, secrets, local paths or health measurements.
• support --feedback --json prints an anonymous setup-feedback bundle for beta testers (guide).
• coverage --live --json prints only redacted data-type status and point-count buckets — never raw Google Health payloads (guide).

Install

Set up a Google Cloud OAuth client (type: Desktop), turn on the Google Health API, and register the local redirect:

http://127.0.0.1:3000/callback

Then run:

npx -y google-health-fitbit-mcp setup --scope-preset full
npx -y google-health-fitbit-mcp auth
npx -y google-health-fitbit-mcp checkup

Scope presets

Presets keep OAuth consent easy to reason about — request only what your use case needs:

Advanced users can pass --scopes with an explicit space/comma-separated scope list.

If setup gets stuck

npx -y google-health-fitbit-mcp checkup --fix        # repairs local config/token permissions (chmod 600 where supported)
npx -y google-health-fitbit-mcp checkup --live       # hits read-only identity/profile/settings endpoints to confirm the API responds
npx -y google-health-fitbit-mcp coverage --live --json  # redacted read-only data-type coverage report
npx -y google-health-fitbit-mcp support             # shareable support bundle, stripped of tokens/secrets/measurements
npx -y google-health-fitbit-mcp support --feedback --json  # anonymous setup feedback bundle

Staying connected

Access tokens refresh silently in the background. The refresh token behind them is what expires — Google revokes it after 7 days while the consent screen is in Testing publishing status, and the next call comes back as invalid_grant. Retrying cannot fix that: the grant is gone, and only a fresh authorization brings it back.

So the server does the authorization for you. On the first call that hits a revoked grant it opens your browser at Google's consent screen; approve, and the original request finishes on its own — no command to run, nothing to diagnose. If you take longer than GOOGLE_HEALTH_REAUTH_WAIT_MS (45s by default), the call returns the URL instead and the listener stays up, so approving still works and the next request goes through.

This only runs on the local stdio transport, where the browser and the server are on the same machine. Under the HTTP transport — where the server may be remote, and its default port collides with the loopback redirect — the call fails with an explicit instruction to run auth instead. Set GOOGLE_HEALTH_AUTO_REAUTH=0 to always handle re-authorization yourself, or GOOGLE_HEALTH_AUTH_NO_BROWSER=1 on headless hosts to get the URL without a browser launch.

MCP client config

Claude Desktop / Cursor / Windsurf (see examples/):

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

Hermes

npx -y google-health-fitbit-mcp setup --client hermes --no-auth
npx -y google-health-fitbit-mcp auth
npx -y google-health-fitbit-mcp checkup --client hermes

Once the config changes, run /reload-mcp or hermes mcp test google_health — there's no need to restart the gateway just to read data.

HTTP transport (optional)

The default transport is stdio. A local Streamable-HTTP transport is available for clients that need it:

npx -y google-health-fitbit-mcp --http   # serves http://127.0.0.1:3000/mcp (+ /health)

Configuration

Reliability built in: every Google call goes through retry middleware (exponential backoff + jitter, honors Retry-After, retries 408/429/5xx) and a 60-second GET-only response cache. Multi-day summaries limit request concurrency to stay under rate limits.

CLI commands

All commands run via npx -y google-health-fitbit-mcp <command> (installed binary: google-health-fitbit-mcp-server).

Beta testers wanted

Right now the most valuable thing you can contribute is hands-on setup feedback from real Fitbit, Pixel Watch, Android and Google Health API accounts.

If you have a real account to test with:

• Run npx -y google-health-fitbit-mcp checkup and let us know whether the OAuth flow reads clearly.
• Run npx -y google-health-fitbit-mcp support --feedback --json and drop the anonymous bundle into a GitHub issue.
• Once OAuth is done, run npx -y google-health-fitbit-mcp coverage --live --json and post the redacted coverage report after you've reviewed it.
• Exercise google_health_connection_status, google_health_data_inventory and google_health_daily_summary from inside your MCP client.
• File an issue if you hit missing data types, unclear setup steps, client-specific friction or privacy concerns.
• Please keep OAuth tokens, client secrets, local paths and personal health measurements out of public issues.

Development

git clone https://github.com/BerkKilicoglu/google-health-fitbit-mcp.git
cd google-health-fitbit-mcp
npm install
npm test

npm test runs typecheck, build, MCP smoke tests (stdio + HTTP), summary fixtures, privacy/cache/retry suites, CLI UX checks and metadata validation. See CONTRIBUTING.md for guidelines and SECURITY.md for the security policy.

Links

• 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 (Fitbit → Google Health): https://developers.google.com/health/migration

Contact & support

• 🐛 Bug reports / feature requests — GitHub Issues
• 📨 klcogluberk@gmail.com — general questions and integration help

License

MIT — see LICENSE.