Skip to content
Back to search

google-health-mcp

Self-hosted MCP server giving AI agents read-only access to your Google Health (Fitbit / Pixel Watch) data. Works with Claude, ChatGPT, Cursor, VS Code and more, including on your phone.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shmsi--google-health-mcp/badge.svg)](/listings/shmsi--google-health-mcp)

HTML

<a href="/listings/shmsi--google-health-mcp"><img src="/api/listings/shmsi--google-health-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| | **Hosted** (Google Cloud Run) | **Local** (on your computer) | |---|---|---| | Works on your phone | ✅ | ❌ | | Works on the web (claude.ai, chatgpt.com) | ✅ | ❌ | | Works in desktop apps and coding tools | ✅ | ✅ | | Needs | A Google Cloud project **with billing**, `gcloud` | Go 1.26+ | | Cost | Usually free for one person (scales to zero) | Free | | Time | ~20 minutes | ~15 minutes |

Most people want **hosted**: set it up once and it works in every app, including the phone.

Either way, you need a Google account whose Fitbit or Pixel Watch data lives in Google Health. If you still sign in to the Fitbit app with an old Fitbit account, finish moving it to Google first.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 472 lines
  1. # google-health-mcp
  2. Ask your AI agent about your Fitbit or Pixel Watch data:
  3. > *"How did I sleep this week compared with last week?"*
  4. > *"Plot my resting heart rate and HRV over the last 60 days."*
  5. > *"What was my heart rate like during yesterday's run?"*
  6. `google-health-mcp` is a small, self-hosted [MCP](https://modelcontextprotocol.io)
  7. server that gives AI agents **read-only** access to your
  8. [Google Health API](https://developers.google.com/health) data: sleep, steps,
  9. activity, heart rate, HRV, SpO2, breathing rate, weight and workouts. It works
  10. with Claude, ChatGPT, Cursor, VS Code, Claude Code and any other MCP client that
  11. supports remote servers with OAuth, including on your phone.
  12. You run it yourself, in your own Google Cloud project. Your data goes from
  13. Google to your server to your agent, and nowhere else.
  14. > **Unofficial.** Not affiliated with Google or Fitbit. Not medical advice.
  15. ---
  16. ## Contents
  17. - [Which setup should I pick?](#which-setup-should-i-pick)
  18. - [Hosted setup (phone, web and desktop)](#hosted-setup-phone-web-and-desktop)
  19. - [Local setup (desktop only)](#local-setup-desktop-only)
  20. - [Connect your agent](#connect-your-agent)
  21. - [What you can ask: the tools](#what-you-can-ask-the-tools)
  22. - [Troubleshooting](#troubleshooting)
  23. - [How it works, and what's stored](#how-it-works-and-whats-stored)
  24. - [Sharing your server with others](#sharing-your-server-with-others)
  25. - [Automatic deploys from GitHub (optional)](#automatic-deploys-from-github-optional)
  26. - [Configuration reference](#configuration-reference)
  27. - [Development](#development)
  28. ---
  29. ## Which setup should I pick?
  30. | | **Hosted** (Google Cloud Run) | **Local** (on your computer) |
  31. |---|---|---|
  32. | Works on your phone | ✅ | ❌ |
  33. | Works on the web (claude.ai, chatgpt.com) | ✅ | ❌ |
  34. | Works in desktop apps and coding tools | ✅ | ✅ |
  35. | Needs | A Google Cloud project **with billing**, `gcloud` | Go 1.26+ |
  36. | Cost | Usually free for one person (scales to zero) | Free |
  37. | Time | ~20 minutes | ~15 minutes |
  38. Most people want **hosted**: set it up once and it works in every app,
  39. including the phone.
  40. Either way, you need a Google account whose Fitbit or Pixel Watch data lives in
  41. Google Health. If you still sign in to the Fitbit app with an old Fitbit
  42. account, finish moving it to Google first.
  43. ---
  44. ## Hosted setup (phone, web and desktop)
  45. You'll create a Google Cloud project, set up a Google sign-in screen for it,
  46. and run one deploy script. Then you add the server's URL to your agent.
  47. ### What you need
  48. - A Google account (the one with your Fitbit or Pixel Watch data).
  49. - A **Google Cloud project with billing enabled**. Create one at
  50. [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate),
  51. then link a billing account under **Billing**. Cloud Run's free tier normally
  52. covers one person's use, but billing must be on.
  53. Project IDs can't contain the word "google". Something like `health-mcp-yourname` works.
  54. - The [`gcloud` CLI](https://cloud.google.com/sdk/docs/install), signed in with
  55. `gcloud auth login`.
  56. - `git`, `bash`, `curl` and `openssl`. macOS and Linux already have them.
  57. On Windows, use [Cloud Shell](https://shell.cloud.google.com), which has everything.
  58. ### Step 1: Get the code and find your server's URL
  59. ```sh
  60. git clone https://github.com/shmsi/google-health-mcp.git
  61. cd google-health-mcp
  62. PROJECT_ID=your-project-id ./deploy/cloudrun.sh url
  63. ```
  64. This doesn't change anything yet. It prints three lines. Keep them handy:
  65. ```
  66. Service URL: https://google-health-mcp-123456789.europe-north1.run.app
  67. MCP URL (for agents): https://google-health-mcp-123456789.europe-north1.run.app/mcp
  68. OAuth redirect URI: https://google-health-mcp-123456789.europe-north1.run.app/oauth/google/callback
  69. ```
  70. The default region is `europe-north1` (Finland). To use another, put
  71. `REGION=us-central1` (or similar) in front of **every** command in this guide.
  72. ### Step 2: Turn on the Google Health API
  73. Open [APIs & Services → Library](https://console.cloud.google.com/apis/library/health.googleapis.com),
  74. check the project picker at the top shows your project, and click **Enable**.
  75. (The deploy script also tries this, but doing it now makes the scopes show up
  76. in step 3.)
  77. ### Step 3: Create the Google sign-in screen
  78. This is the screen you see when you connect your agent. All of it is in
  79. **Google Auth Platform** in the Cloud Console.
  80. 1. **[Branding](https://console.cloud.google.com/auth/branding)**. If you see
  81. **Get started**, click it. Enter an app name (for example *Health MCP*) and
  82. your email, choose **External** as the audience, and finish the wizard.
  83. 2. **[Audience](https://console.cloud.google.com/auth/audience)**.
  84. - Leave **Publishing status** on **Testing**. Don't publish the app.
  85. - Under **Test users**, click **Add users** and add your own Google account.
  86. Only test users can sign in.
  87. 3. **[Data Access](https://console.cloud.google.com/auth/scopes)** → **Add or remove scopes**.
  88. - Tick `openid` and `.../auth/userinfo.email`.
  89. - Under **Manually add scopes**, paste these five lines and click **Add to table**:
  90. ```
  91. https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  92. https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  93. https://www.googleapis.com/auth/googlehealth.sleep.readonly
  94. https://www.googleapis.com/auth/googlehealth.profile.readonly
  95. https://www.googleapis.com/auth/googlehealth.settings.readonly
  96. ```
  97. - Click **Update**, then **Save**.
  98. 4. **[Clients](https://console.cloud.google.com/auth/clients)** → **Create client**.
  99. - Application type: **Web application**.
  100. - Under **Authorized redirect URIs**, add the **OAuth redirect URI** from step 1.
  101. It must match exactly.
  102. - Click **Create**. Copy the **Client ID** and the **Client secret**.
  103. ### Step 4: Deploy
  104. Replace the values and run:
  105. ```sh
  106. PROJECT_ID=your-project-id \
  107. ALLOWED_EMAILS=you@gmail.com \
  108. GOOGLE_OAUTH_CLIENT_ID=1234-abc.apps.googleusercontent.com \
  109. GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-your-secret \
  110. GOOGLE_HEALTH_TZ=Europe/Stockholm \
  111. ./deploy/cloudrun.sh deploy
  112. ```
  113. - `ALLOWED_EMAILS`: the Google account(s) allowed to connect, comma-separated.
  114. - `GOOGLE_HEALTH_TZ`: your [time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones),
  115. so "today" and "last night" mean what you expect. The default is UTC.
  116. The first run takes about 5 minutes. The script enables the APIs it needs,
  117. creates an encryption key, stores the client secret in Secret Manager, builds
  118. the server with Cloud Build and deploys it. It ends with:
  119. ```
  120. ==> Health check OK
  121. Done. Add this as a custom connector / remote MCP server in your agent:
  122. https://google-health-mcp-123456789.europe-north1.run.app/mcp
  123. ```
  124. **Check:** open the **Service URL** in a browser. You should see a short page
  125. titled *Google Health MCP* with your MCP URL on it.
  126. ### Step 5: Connect your agent
  127. Add the **MCP URL** (ending in `/mcp`) to your agent. See
  128. [Connect your agent](#connect-your-agent) for where that setting is in each app.
  129. When you click **Connect**:
  130. 1. This server's own page asks you to confirm the app that's connecting. Click **Continue with Google**.
  131. 2. Google warns that it **hasn't verified this app**. That's expected for a
  132. personal app in Testing mode, and the app is yours. Click **Continue**.
  133. 3. Choose your account, allow the permissions, and you're sent back to your agent.
  134. Then ask: *"How did I sleep last night?"*
  135. ### Keeping it running
  136. - **Reconnect weekly.** While the sign-in screen is in Testing mode, Google
  137. ends the sign-in after **7 days**. Your agent then asks you to connect again,
  138. which takes a few seconds. The only way around this is
  139. [publishing the app](#sharing-your-server-with-others), which needs Google's verification.
  140. - **Updating.** `git pull`, then run the deploy command from step 4 again. You can
  141. leave out `GOOGLE_OAUTH_CLIENT_SECRET`, because it's already stored. Keep
  142. `GOOGLE_HEALTH_TZ`, or it goes back to UTC. To deploy on every push instead, see
  143. [Automatic deploys](#automatic-deploys-from-github-optional).
  144. - **Stopping it.** Delete the Cloud Run service, or the whole project, in the
  145. Cloud Console. Revoke the app's access at
  146. [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
  147. ---
  148. ## Local setup (desktop only)
  149. The server runs on your computer, and your desktop app starts it when needed.
  150. No Cloud Run, no billing.
  151. ### Step 1: Google Cloud project and sign-in screen
  152. 1. Create a project at [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate). Billing isn't needed.
  153. 2. [Enable the Google Health API](https://console.cloud.google.com/apis/library/health.googleapis.com).
  154. 3. Set up **Branding**, **Audience** (Testing, add yourself as a test user) and
  155. **Data Access** (the five `googlehealth` scopes) exactly as in
  156. [hosted step 3](#step-3-create-the-google-sign-in-screen). You don't need
  157. `openid` or `email` locally.
  158. 4. **[Clients](https://console.cloud.google.com/auth/clients)** → **Create client** →
  159. Application type **Desktop app** → **Create**, then **Download JSON**.
  160. ### Step 2: Save the client file
  161. Save the downloaded file as `credentials.json` in this folder (create it if needed):
  162. | OS | Folder |
  163. |---|---|
  164. | macOS | `~/Library/Application Support/google-health-mcp/` |
  165. | Linux | `~/.config/google-health-mcp/` |
  166. | Windows | `%AppData%\google-health-mcp\` |
  167. Alternatively, set `GOOGLE_HEALTH_CLIENT_ID` and `GOOGLE_HEALTH_CLIENT_SECRET`
  168. instead of using the file. Set `GOOGLE_HEALTH_MCP_DIR` to use another folder.
  169. ### Step 3: Install and sign in
  170. ```sh
  171. go install github.com/shmsi/google-health-mcp@latest
  172. google-health-mcp login # opens your browser; tick every permission
  173. google-health-mcp status # checks the connection
  174. ```
  175. `go install` puts the binary in `$(go env GOPATH)/bin`. Make sure that's on
  176. your `PATH`, or use the full path below.
  177. ### Step 4: Add it to your app
  178. Most desktop apps (Claude Desktop, Cursor and others) use this format. In
  179. Claude Desktop it goes in `claude_desktop_config.json`, and in Cursor in
  180. `~/.cursor/mcp.json`:
  181. ```json
  182. {
  183. "mcpServers": {
  184. "google-health": {
  185. "command": "/full/path/to/google-health-mcp",
  186. "env": { "GOOGLE_HEALTH_TZ": "Europe/Stockholm" }
  187. }
  188. }
  189. }
  190. ```
  191. VS Code uses `"servers"` instead of `"mcpServers"` and adds `"type": "stdio"`.
  192. For Claude Code:
  193. ```sh
  194. claude mcp add google-health -e GOOGLE_HEALTH_TZ=Europe/Stockholm -- /full/path/to/google-health-mcp
  195. ```
  196. Restart the app and ask: *"How did I sleep last night?"*
  197. In Testing mode the sign-in lasts 7 days. When it expires, run
  198. `google-health-mcp login` again.
  199. ---
  200. ## Connect your agent
  201. Your agent needs the **MCP URL**: your service URL followed by `/mcp`.
  202. | Client | Where |
  203. |---|---|
  204. | **Claude** (web, phone, desktop) | **Settings → Connectors → Add custom connector**. Add it on claude.ai and it appears in the phone and desktop apps too. |
  205. | **ChatGPT** | Custom connectors / apps in **Settings**. Depending on your plan, you may need to turn on developer mode. |
  206. | **Claude Code** | `claude mcp add --transport http google-health https://…/mcp` |
  207. | **VS Code** | `.vscode/mcp.json`: `{"servers": {"google-health": {"type": "http", "url": "https://…/mcp"}}}` |
  208. | **Cursor** | `~/.cursor/mcp.json`: `{"mcpServers": {"google-health": {"url": "https://…/mcp"}}}` |
  209. | **Anything else** | Any client with remote MCP (Streamable HTTP) and OAuth support. Leave client ID and secret empty: the server registers clients automatically. |
  210. Most phone apps can't add connectors from the phone. Add it on the web version
  211. once, and it shows up on your phone. Menu names change often, so check your
  212. app's docs if these don't match.
  213. ---
  214. ## What you can ask: the tools
  215. | Tool | What it's for |
  216. |---|---|
  217. | `get_daily_overview` | One call for 1–31 days: steps, distance, floors, Active Zone Minutes and calories, plus resting HR, HRV, SpO2, breathing rate, sleep sessions and workouts |
  218. | `get_daily_totals` | Per-day (or per-N-day) totals for trends, such as steps over the last 90 days or weekly Active Zone Minutes |
  219. | `get_data_points` | Raw records: sleep sessions with stages, workouts, daily summaries, weight. Uses the *reconciled* stream, which merges overlapping devices the way the Fitbit app does. |
  220. | `get_rollup` | Time buckets within a day, such as heart rate every 5 minutes during a run, or steps per hour |
  221. | `get_account_info` | Connection check, profile, settings, paired devices, and the server's idea of "today" |
  222. | `list_data_types` | The supported data types and which tools work with each |
  223. Dates can be `YYYY-MM-DD`, `today`, `yesterday` or relative like `-7d`. Sleep
  224. counts for the day it **ended**, so "last night" is today's date.
  225. More prompts to try:
  226. - *"Compare my average steps this month with last month."*
  227. - *"On which days last week did I get less than 7 hours of sleep?"*
  228. - *"Show my weight trend since January."*
  229. - *"How much time did I spend in deep sleep on average this week?"*
  230. ---
  231. ## Troubleshooting
  232. **"Access blocked: … has not completed the Google verification process" / `access_denied`.**
  233. The Google account isn't a test user. Add it under
  234. [Audience → Test users](https://console.cloud.google.com/auth/audience).
  235. **`Error 400: redirect_uri_mismatch`.**
  236. The redirect URI on your OAuth client doesn't exactly match the server's. Run
  237. `./deploy/cloudrun.sh url` again and copy the **OAuth redirect URI** into the
  238. client under [Clients](https://console.cloud.google.com/auth/clients).
  239. **"The Google account … is not allowed to use this server."**
  240. That account isn't in `ALLOWED_EMAILS`. Re-run the deploy with it added.
  241. **It worked for a week, then stopped.**
  242. The 7-day sign-in limit of Testing mode. Reconnect in your agent.
  243. **`ACCOUNT_NOT_LINKED` from `get_account_info`.**
  244. Your Fitbit or Pixel Watch data isn't attached to that Google account yet. Finish
  245. moving your Fitbit account to Google in the Fitbit app.
  246. **The deploy fails with a billing or permission error.**
  247. Make sure billing is enabled on the project, and that your `gcloud` account is
  248. an owner or editor of it. If Cloud Build reports a permission error, grant
  249. `roles/run.builder` to the `<project-number>-compute@developer.gserviceaccount.com`
  250. service account under **IAM**.
  251. **A question fails for one kind of data, while others work.**
  252. The API filters each data type on a different time field, and the mapping in
  253. `internal/health/catalog.go` is partly a best guess. Please
  254. [open an issue](https://github.com/shmsi/google-health-mcp/issues) with the
  255. data type and the error message.
  256. **Checking the server's logs.**
  257. ```sh
  258. gcloud run services logs read google-health-mcp --region europe-north1 --project your-project-id
  259. ```
  260. The logs never contain email addresses. Users show up as short anonymous IDs.
  261. ---
  262. ## How it works, and what's stored
  263. ```
  264. Agent ──OAuth (DCR + PKCE)──▶ google-health-mcp ──Google sign-in──▶ Google
  265. │ (consent page) │
  266. └──── MCP over HTTPS ─────────────────────▶└──── Google Health API
  267. ```
  268. - **Nothing about your health is stored.** Each time your agent asks, the server
  269. reads from Google, formats the answer and passes it straight through.
  270. - **Your Google sign-in is held by your agent, encrypted.** After you sign in,
  271. Google gives the server a refresh token. The server encrypts it (AES-256-GCM)
  272. inside the tokens it hands your agent, and keeps no copy. If the server
  273. restarts, your connection keeps working.
  274. - **The encryption key** is generated at deploy time and kept in Secret Manager,
  275. readable only by the server's own service account. Rotating it signs every
  276. agent out.
  277. - **Logs** contain no emails or health data. Users appear as short anonymous IDs.
  278. - **Read-only.** The server never asks Google for write access.
  279. - **Once an answer reaches your agent,** it's part of your chat history with that
  280. provider (Anthropic, OpenAI…) under their terms.
  281. **Why the consent page?** Any MCP client can register with the server: that's
  282. how "just paste the URL" works. To stop someone tricking you into connecting
  283. *their* app, every connection first shows which app is asking and where you'll
  284. be sent back. The page is tied to your browser, so it can't be skipped by
  285. sending you a Google sign-in link directly.
  286. ---
  287. ## Sharing your server with others
  288. To let friends or family use your server:
  289. 1. Add each person's Google account as a **test user** under
  290. [Audience](https://console.cloud.google.com/auth/audience). Testing mode allows up to 100.
  291. 2. Re-deploy with their emails in `ALLOWED_EMAILS`, or use `ALLOWED_EMAILS='*'`
  292. to accept every account Google lets sign in (in Testing mode, that's only
  293. your test users).
  294. Each person signs in with their own Google account and sees only their own
  295. data. Their sign-in lives in their own agent, not on your server.
  296. Opening it to **anyone**, without adding them by hand and without the weekly
  297. reconnect, means publishing the app. The Google Health scopes are *restricted*,
  298. so publishing requires Google's verification: a privacy policy, a verified
  299. domain and usually a yearly third-party security assessment. That's meant for
  300. businesses, not personal servers.
  301. ---
  302. ## Automatic deploys from GitHub (optional)
  303. If you fork this repo, it can deploy itself on every push to `main`:
  304. ```sh
  305. PROJECT_ID=your-project-id GITHUB_REPO=you/google-health-mcp ./deploy/setup-github-ci.sh
  306. ```
  307. Run it after the first deploy. It sets up keyless authentication
  308. (Workload Identity Federation, trusted only for your repo's `main` branch) and a
  309. deployer service account with minimal permissions, and it sets the repository
  310. variables the workflow needs (using `gh` if installed). From then on, every push
  311. to `main` runs the tests, builds the image, deploys it and checks it's healthy.
  312. Until those variables are set, the deploy job is skipped.
  313. CI only replaces the server's code. Settings such as allowed emails and the time
  314. zone stay as the deploy script set them.
  315. ---
  316. ## Configuration reference
  317. **Hosted server** (`google-health-mcp serve-http`), set by `deploy/cloudrun.sh`:
  318. | Variable | Meaning |
  319. |---|---|
  320. | `PUBLIC_URL` | The server's public https URL |
  321. | `ALLOWED_EMAILS` | Google accounts allowed to connect, comma-separated, or `*` for any account Google allows |
  322. | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` | The Web application OAuth client |
  323. | `MCP_SIGNING_KEY` | Base64, at least 32 random bytes. Encrypts all issued tokens. |
  324. | `GOOGLE_HEALTH_TZ` | Time zone for "today" (default UTC) |
  325. | `GOOGLE_HEALTH_EXTRA_SCOPES` | Extra read scopes, such as `nutrition.readonly,ecg.readonly`. Add them to the sign-in screen too. |
  326. | `ALLOWED_REDIRECT_HOSTS` | Optional strict mode: only these hosts may register as clients, such as `claude.ai,claude.com,localhost,127.0.0.1`. App schemes like `cursor://` are refused. |
  327. | `PORT` | Listen port (default 8080) |
  328. `deploy/cloudrun.sh` also accepts `REGION` (default `europe-north1`) and
  329. `SERVICE` (default `google-health-mcp`).
  330. **Local server** (`google-health-mcp`):
  331. | Flag / variable | Meaning |
  332. |---|---|
  333. | `-tz` / `GOOGLE_HEALTH_TZ` | Time zone for "today" (default: your computer's) |
  334. | `-extra-scopes` / `GOOGLE_HEALTH_EXTRA_SCOPES` | Extra read scopes to request at `login` |
  335. | `-no-browser` | `login` prints the URL instead of opening a browser |
  336. | `GOOGLE_HEALTH_MCP_DIR` | Where `credentials.json` and the token are kept |
  337. | `logout` | Deletes the saved token |
  338. **Limits.** `get_data_points` returns at most about 200 records (about 120 KB)
  339. and says when it stopped. Dense data such as heart rate belongs in `get_rollup`
  340. or `get_daily_totals`. The API's maximum date ranges (90 days, or 14 for some
  341. types) are handled by splitting requests.
  342. ---
  343. ## Development
  344. ```sh
  345. go test -race ./... # unit tests, against a fake API
  346. go run . serve # local stdio server
  347. ```
  348. | Path | What's there |
  349. |---|---|
  350. | `main.go` | Commands: `login`, `status`, `logout`, `serve`, `serve-http` |
  351. | `internal/remote` | Hosted mode: OAuth server for MCP clients, consent page, Google sign-in, Streamable HTTP |
  352. | `internal/auth` | Local mode: browser login with PKCE, token file |
  353. | `internal/health` | Google Health API client, data-type catalog, date parsing |
  354. | `internal/tools` | The MCP tools |
  355. | `internal/testapi` | Fake API for tests |
  356. | `deploy/`, `Dockerfile` | Cloud Run deploy script, CI bootstrap, container image |
  357. Issues and pull requests are welcome. Security problems: see [SECURITY.md](SECURITY.md).
  358. ## License
  359. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.