\n Query your own Google Health API data — Fitbit, Pixel Watch and connected partner sources — over local OAuth. Beta. \n Everything runs on your own machine — your credentials never leave your device.\n
\n\n
\n \n \n \n \n \n
\n\n---\n\n**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.**\n\n- **Install in one command** — `npx -y google-health-fitbit-mcp setup`\n- **Run it in** Claude Desktop · Claude Code · Cursor · Windsurf · Hermes · OpenClaw — see [client examples](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/tree/main/examples).\n- **On your machine** — OAuth tokens are stored locally with `0600` permissions and are never returned by any tool ([privacy](#privacy--what-runs-offline)).\n- **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.\n\n> **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.\n\n> 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.\n\n## ⚡ Quick Connect\n\n> Prerequisite: a Google Cloud OAuth client (type: Desktop) with the [Google Health API](https://console.cloud.google.com/apis/library/health.googleapis.com) enabled and the redirect `http://127.0.0.1:3000/callback` registered — details in [Install](#install).\n\n**Step 1 — Install & authorize (once):**\n\n```bash\nnpx -y google-health-fitbit-mcp setup # guided: Google Cloud OAuth client + scopes\nnpx -y google-health-fitbit-mcp auth # browser OAuth — tokens stay on your machine\nnpx -y google-health-fitbit-mcp checkup # ✓ verifies everything is ready\n```\n\n\n🔑 First time? Get your Google Client ID & Secret (~2 min)\n\n`setup` asks for a **Client ID** and **Client Secret**. You create these once, for free, in Google Cloud:\n\n1. **New project** — open [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate), name it (e.g. `health-mcp`), click **Create**, then select it.\n2. **Enable the API** — open the [Google Health API](https://console.cloud.google.com/apis/library/health.googleapis.com) page and click **Enable**.\n3. **Consent screen** — go to [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent), choose **External**, and fill in the required app name / email fields. Under **Test users**, **add your own Google account** — skip this and sign-in fails with `403: access_denied`.\n4. **Create the client** — go to [Credentials](https://console.cloud.google.com/apis/credentials) → **+ Create credentials → OAuth client ID** → **Application type: Desktop app** → **Create**.\n5. **Copy** the **Client ID** (ends in `…apps.googleusercontent.com`) and the **Client secret**, then paste each one when `setup` prompts you.\n\n> **Redirect URI:** Desktop-app clients allow the `http://127.0.0.1:3000/callback` loopback automatically — you don't register it anywhere. Just press **Enter** to accept the default when `setup` asks. For every other `setup` prompt (scope preset, privacy mode), pressing **Enter** picks a sensible default.\n\n> **Heads-up — the 7-day rule:** while the consent screen sits in **Testing** publishing status, Google revokes refresh tokens after 7 days. Around once a week the next request fails with `invalid_grant`, which is normal and not a bug in this server. It reopens the consent flow for you (see [Staying connected](#staying-connected)); approving takes a couple of seconds. Publishing the app removes the expiry entirely — check what your scopes require on the consent screen before switching.\n\n\n\n**Step 2 — Connect your app:**\n\n\nClaude Code\n\n```bash\nclaude mcp add google-health -- npx -y google-health-fitbit-mcp\n```\n\n\n\n\nClaude Desktop\n\nSettings → Developer → Edit Config, then add to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"google_health\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"google-health-fitbit-mcp\"]\n }\n }\n}\n```\n\nRestart Claude Desktop — the tools appear under the 🔌 connectors menu.\n\n\n\n\nCursor\n\nAdd the same `mcpServers` block to `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global), or use Settings → MCP → Add new server.\n\n```json\n{\n \"mcpServers\": {\n \"google_health\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"google-health-fitbit-mcp\"]\n }\n }\n}\n```\n\n\n\n\nWindsurf\n\nAdd the same `mcpServers` block to `~/.codeium/windsurf/mcp_config.json`.\n\n\n\n\nHermes\n\n```bash\nnpx -y google-health-fitbit-mcp setup --client hermes # writes the Hermes config for you\n```\n\nThen reload with `/reload-mcp` or `hermes mcp test google_health`.\n\n\n\n**Step 3 — Test it.** Ask your agent:\n\n```text\nRun google_health_connection_status and tell me if I'm connected.\n```\n\n## Why this exists\n\nThe 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.\n\nIt 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.\n\n## Try it with your agent\n\nThree good opening prompts, built around tools this connector genuinely ships:\n\n```text\nCheck my setup with google_health_connection_status, then call\ngoogle_health_data_inventory and tell me which Google Health\ndomains and scopes I've granted.\n```\n\n```text\nPull today's google_health_daily_summary, then google_health_weekly_summary.\nKeep observed data separate from any suggestions, and stay non-medical.\n```\n\n```text\nList my paired devices with google_health_list_paired_devices and tell me\nwhich device is producing my sleep and heart-rate data.\n```\n\n## Tools\n\n29 tools, all read-only except the two explicitly gated local-profile/auth actions noted below.\n\n### Start here\n\n| Tool | What it does |\n|---|---|\n| `google_health_connection_status` | Local config, token, scope and MCP-client readiness — no Google call |\n| `google_health_quickstart` | Personalized 3-step setup walkthrough that adapts to your current state |\n| `google_health_data_inventory` | Supported domains, scopes, data-type naming and recommended agent flow |\n| `google_health_list_data_types` | The 39 kebab-case data-type slugs with units, scopes and supported verbs |\n| `google_health_demo` | Realistic synthetic payloads so agents see the contract before real calls |\n\n### Data reads (Google Health API)\n\n| Tool | Endpoint |\n|---|---|\n| `google_health_get_identity` | `/v4/users/me/identity` — Google Health + legacy Fitbit identity mapping |\n| `google_health_get_profile` | `/v4/users/me/profile` |\n| `google_health_get_settings` | `/v4/users/me/settings` — units, timezone |\n| `google_health_list_paired_devices` | `/v4/users/me/pairedDevices` — your Fitbit trackers and Pixel Watches, and which device produces which data |\n| `google_health_get_irn_profile` | `/v4/users/me/irnProfile` — irregular-rhythm (AFib) notification engagement status |\n| `google_health_list_data_points` | `/v4/.../dataPoints` — intraday detail for any data type |\n| `google_health_get_data_point` | `/v4/.../dataPoints/{id}` — one specific sleep session, exercise or measurement |\n| `google_health_reconcile_data_points` | `/v4/.../dataPoints:reconcile` — one clean stream across sources (all-sources, google-wearables, google-sources) |\n| `google_health_daily_rollup` | `/v4/.../dataPoints:dailyRollUp` — civil-day aggregates |\n| `google_health_rollup` | `/v4/.../dataPoints:rollUp` — physical-time window aggregates |\n\n### Summaries & wellness context\n\n| Tool | What it does |\n|---|---|\n| `google_health_daily_summary` | Steps, distance, calories, active-zone minutes, sleep, resting HR, HRV and weight for one day, with data-quality flags |\n| `google_health_weekly_summary` | Weekly scorecard with optional prior-window comparison, load classification and bottlenecks |\n| `google_health_wellness_context` | Normalized activity/sleep context for recommendation engines |\n\n### Auth, diagnostics & metadata\n\n`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`)\n\n### Resources & prompts\n\nMCP 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`.\n\nMCP prompts: `google_health_daily_checkin`, `google_health_weekly_review`, `google_health_data_type_investigation`.\n\n## Data types\n\n39 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`.\n\nNaming rules agents need:\n\n- **Endpoints** use kebab-case data types: `steps`, `daily-resting-heart-rate`.\n- **Filters** use snake_case field paths: `sleep.interval.civil_start_time`, `heart_rate.sample_time.physical_time`.\n- **Source families**: `all-sources`, `google-wearables`, `google-sources`.\n\nCall `google_health_list_data_types` for the full catalog with units, scopes and which verbs (list/reconcile/rollup) each type supports.\n\n## Privacy & what runs offline\n\n- OAuth tokens live on disk at `~/.google-health-mcp/tokens.json`, locked down to `0600` permissions.\n- Client secrets go in `~/.google-health-mcp/config.json` or the `GOOGLE_HEALTH_*` environment variables.\n- No tool ever hands back an access token, refresh token or client secret; error output is redacted too.\n- The default privacy mode is `GOOGLE_HEALTH_PRIVACY_MODE=structured`; `summary` strips identifiers further, and `raw` is an explicit opt-in for debugging.\n- GPS/route data is treated as sensitive and redacted unless explicitly requested.\n- `support` prints a copy-paste support bundle for GitHub issues — always redacted, never contains tokens, secrets, local paths or health measurements.\n- `support --feedback --json` prints an anonymous setup-feedback bundle for beta testers ([guide](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/docs/setup-feedback.md)).\n- `coverage --live --json` prints only redacted data-type status and point-count buckets — never raw Google Health payloads ([guide](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/docs/data-coverage.md)).\n\n## Install\n\nSet up a Google Cloud OAuth client (type: Desktop), turn on the [Google Health API](https://console.cloud.google.com/apis/library/health.googleapis.com), and register the local redirect:\n\n```text\nhttp://127.0.0.1:3000/callback\n```\n\nThen run:\n\n```bash\nnpx -y google-health-fitbit-mcp setup --scope-preset full\nnpx -y google-health-fitbit-mcp auth\nnpx -y google-health-fitbit-mcp checkup\n```\n\n### Scope presets\n\nPresets keep OAuth consent easy to reason about — request only what your use case needs:\n\n| Preset | Grants |\n|---|---|\n| `basic` | profile + settings |\n| `activity` | basic + activity/fitness + health metrics |\n| `sleep` | basic + sleep |\n| `heart` | basic + health metrics + **ECG** + **irregular-rhythm notifications** |\n| `full` | all recommended read-only scopes (default) |\n| `nutrition-write` | opt-in nutrition write scope — the only preset with any write capability; no write tool ships yet |\n\nAdvanced users can pass `--scopes` with an explicit space/comma-separated scope list.\n\n### If setup gets stuck\n\n```bash\nnpx -y google-health-fitbit-mcp checkup --fix # repairs local config/token permissions (chmod 600 where supported)\nnpx -y google-health-fitbit-mcp checkup --live # hits read-only identity/profile/settings endpoints to confirm the API responds\nnpx -y google-health-fitbit-mcp coverage --live --json # redacted read-only data-type coverage report\nnpx -y google-health-fitbit-mcp support # shareable support bundle, stripped of tokens/secrets/measurements\nnpx -y google-health-fitbit-mcp support --feedback --json # anonymous setup feedback bundle\n```\n\n### Staying connected\n\nAccess 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.\n\nSo 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.\n\nThis 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.\n\n### MCP client config\n\nClaude Desktop / Cursor / Windsurf (see [examples/](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/tree/main/examples)):\n\n```json\n{\n \"mcpServers\": {\n \"google_health\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"google-health-fitbit-mcp\"]\n }\n }\n}\n```\n\n### Hermes\n\n```bash\nnpx -y google-health-fitbit-mcp setup --client hermes --no-auth\nnpx -y google-health-fitbit-mcp auth\nnpx -y google-health-fitbit-mcp checkup --client hermes\n```\n\nOnce the config changes, run `/reload-mcp` or `hermes mcp test google_health` — there's no need to restart the gateway just to read data.\n\n### HTTP transport (optional)\n\nThe default transport is stdio. A local Streamable-HTTP transport is available for clients that need it:\n\n```bash\nnpx -y google-health-fitbit-mcp --http # serves http://127.0.0.1:3000/mcp (+ /health)\n```\n\n## Configuration\n\n| Environment variable | Purpose | Default |\n|---|---|---|\n| `GOOGLE_HEALTH_CLIENT_ID` | Google Cloud OAuth client ID | — (or local config) |\n| `GOOGLE_HEALTH_CLIENT_SECRET` | OAuth client secret (prefer local config over MCP client config) | — (or local config) |\n| `GOOGLE_HEALTH_REDIRECT_URI` | Registered redirect URI | — (or local config) |\n| `GOOGLE_HEALTH_TOKEN_PATH` | Token file location | `~/.google-health-mcp/tokens.json` |\n| `GOOGLE_HEALTH_PRIVACY_MODE` | `summary` \\| `structured` \\| `raw` | `structured` |\n| `GOOGLE_HEALTH_CACHE` | Optional SQLite response cache (`true`/`sqlite`) | disabled |\n| `GOOGLE_HEALTH_CACHE_PATH` | SQLite cache location | `~/.google-health-mcp/cache.sqlite` |\n| `GOOGLE_HEALTH_NO_CACHE` | Bypass the in-memory HTTP cache (60s TTL, GET-only) | unset |\n| `GOOGLE_HEALTH_MCP_TRANSPORT` | `stdio` \\| `http` | `stdio` |\n| `GOOGLE_HEALTH_MCP_HOST` / `GOOGLE_HEALTH_MCP_PORT` | HTTP transport bind address | `127.0.0.1` / `3000` |\n| `GOOGLE_HEALTH_AUTO_REAUTH` | Reopen the consent flow automatically when the grant is revoked (`0`/`false` to disable) | enabled |\n| `GOOGLE_HEALTH_REAUTH_WAIT_MS` | How long a tool call waits for you to approve before returning the URL instead | `45000` |\n| `GOOGLE_HEALTH_AUTH_NO_BROWSER` | Never launch a browser; print/return the URL only (headless hosts) | unset |\n\nReliability 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.\n\n## CLI commands\n\nAll commands run via `npx -y google-health-fitbit-mcp ` (installed binary: `google-health-fitbit-mcp-server`).\n\n| Command | What it does | Key flags |\n|---|---|---|\n| *(none)* | Start the MCP server on stdio | `--http` — local Streamable-HTTP on `127.0.0.1:3000/mcp` |\n| `setup` | Guided setup: writes local config + MCP client config | `--scope-preset ` · `--scopes \"\"` · `--client ` · `--no-auth` · `--json` |\n| `auth` | Browser OAuth with local callback; saves tokens with `0600` permissions | `--no-open` — print the auth URL instead of opening the browser |\n| `checkup` | Setup diagnosis with ✓/✗ checks and next steps (aliases: `doctor`, `status`) | `--json` · `--client ` · `--fix` — repair file permissions · `--live` — prove API reachability · `--live-write` — dry-run the write path, never POSTs |\n| `coverage` | Data-type coverage report across list/reconcile/rollup | `--json` · `--live` — redacted read-only checks against your real account |\n| `support` | Redacted support bundle for GitHub issues | `--json` · `--feedback` — anonymous setup-feedback bundle |\n| `onboarding` | Shared wellness onboarding flow as JSON | `--pt-BR` |\n| `version` / `help` | Print version / full usage | |\n\n## Beta testers wanted\n\nRight now the most valuable thing you can contribute is hands-on setup feedback from real Fitbit, Pixel Watch, Android and Google Health API accounts.\n\nIf you have a real account to test with:\n\n- Run `npx -y google-health-fitbit-mcp checkup` and let us know whether the OAuth flow reads clearly.\n- Run `npx -y google-health-fitbit-mcp support --feedback --json` and drop the anonymous bundle into a GitHub issue.\n- 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.\n- Exercise `google_health_connection_status`, `google_health_data_inventory` and `google_health_daily_summary` from inside your MCP client.\n- File an issue if you hit missing data types, unclear setup steps, client-specific friction or privacy concerns.\n- Please keep OAuth tokens, client secrets, local paths and personal health measurements **out of** public issues.\n\n## Development\n\n```bash\ngit clone https://github.com/BerkKilicoglu/google-health-fitbit-mcp.git\ncd google-health-fitbit-mcp\nnpm install\nnpm test\n```\n\n`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](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/CONTRIBUTING.md) for guidelines and [SECURITY.md](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/SECURITY.md) for the security policy.\n\n## Links\n\n- Google Health API: https://developers.google.com/health\n- Release notes: https://developers.google.com/health/release-notes\n- REST reference: https://developers.google.com/health/reference/rest\n- Scopes: https://developers.google.com/health/scopes\n- Data types: https://developers.google.com/health/data-types\n- Migration guide (Fitbit → Google Health): https://developers.google.com/health/migration\n\n## Contact & support\n\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/issues)\n- 📨 **klcogluberk@gmail.com** — general questions and integration help\n\n## License\n\nMIT — see [LICENSE](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/LICENSE).",
"bytes": 21983,
"sha": "b0117bd4b3f73a846dcb2e471b11eec665e327cf1ae4e9b86e19b5984e81e25d",
"repo_slug": "berkkilicoglu/google-health-fitbit-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_berkkilicoglu_google_health_fi_8cd08bde/readme"
}
![\"Google](\"https://raw.githubusercontent.com/BerkKilicoglu/google-health-fitbit-mcp/main/assets/banner.png\")
\n![\"npm](\"https://img.shields.io/npm/v/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white\")
![\"npm](\"https://img.shields.io/npm/dt/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white\")
![\"License](\"https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Built](\"https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/BerkKilicoglu/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github\")