google-health-mcp-server

A complete, open-source single tenant MCP server for the Google Health API v4 -- the OAuth-based successor to the Fitbit Web API. Every method reachable with just a user's own OAuth grant is exposed as a tool below, including profile/settings, paired devices, raw data points, source reconciliation, and both physical- and civil-time rollups.

Runs two ways:

• Locally over stdio -- for Claude Desktop / Claude Code, zero hosting required.

• Remotely over HTTP -- for claude.ai / Cowork connectors, deployable to Fly.io with the included Dockerfile.

View the full product and technical design here.

Tools

17 tools cover every non-Cloud-IAM method in the API. Full list with exact endpoint coverage: docs/tools.md.

Related MCP server: fitbit-google-health-mcp

One-time setup: getting a refresh token

This server acts on behalf of one Google account (yours). Before running it, you need an OAuth client and a refresh token for that account:

1. Follow Set up Google Cloud and OAuth to enable the Google Health API on a Google Cloud project and create a Web application OAuth 2.0 Client ID. Use https://developers.google.com/oauthplayground as an authorized redirect URI if you plan to use the OAuth Playground for the next step (or run your own short local script).

2. Add yourself as a test user for the OAuth consent screen, and add the scopes you want this instance to use (e.g. .../auth/googlehealth.activity_and_fitness.readonly, .../auth/googlehealth.sleep.readonly).

3. Using the OAuth 2.0 Playground (gear icon → "Use your own OAuth credentials" → paste your client ID/secret), authorize the scopes from step 2 against your Google account, then exchange the authorization code for tokens. Copy the refresh token it returns.

4. You now have the three values this server needs: GOOGLE_HEALTH_CLIENT_ID, GOOGLE_HEALTH_CLIENT_SECRET, GOOGLE_HEALTH_REFRESH_TOKEN.

Note: while your OAuth consent screen is in Testing status, refresh tokens expire after 7 days and need to be re-minted. Publish the consent screen (or request verification) for a long-lived refresh token -- see Token behavior during testing.

Quick start (local, stdio)

Requires Node.js 20+.

npx google-health-mcp-server

Point your MCP client (Claude Desktop, Claude Code, etc.) at it. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-health": {
      "command": "npx",
      "args": ["google-health-mcp-server"],
      "env": {
        "GOOGLE_HEALTH_CLIENT_ID": "your-client-id",
        "GOOGLE_HEALTH_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_HEALTH_REFRESH_TOKEN": "your-refresh-token",
        "GOOGLE_HEALTH_READ_ONLY": "false"
      }
    }
  }
}

Configuration

HTTP mode (below) needs three more: PORT, PUBLIC_URL, MCP_HTTP_PASSWORD. See .env.example for all of them with descriptions.

Remote (HTTP) deployment on Fly.io

The HTTP transport is gated by OAuth (required for claude.ai/Cowork connector approval). This is single-tenant OAuth, and it is a separate concern from the Google OAuth grant above: it just gates access to your instance behind one shared password, not per-user Google accounts. See docs/architecture.md for why and how.

1. Install flyctl and fly auth login.

2. fly launch --no-deploy from this directory (it will read fly.toml; rename the app there first if you want a specific subdomain).

3. Set secrets (never put these in fly.toml, which is committed to git):

   fly secrets set GOOGLE_HEALTH_CLIENT_ID=your-client-id
   fly secrets set GOOGLE_HEALTH_CLIENT_SECRET=your-client-secret
   fly secrets set GOOGLE_HEALTH_REFRESH_TOKEN=your-refresh-token
   fly secrets set MCP_HTTP_PASSWORD=choose-a-strong-password

4. Edit fly.toml's PUBLIC_URL to match your actual *.fly.dev hostname (or custom domain), then:

   fly deploy

5. In claude.ai / Cowork, add a custom connector pointing at https://<your-app>.fly.dev/mcp. You'll be redirected to a login page on your own instance -- enter MCP_HTTP_PASSWORD to approve the connection.

Notes:

• Single shared-cpu-1x machine, no volume. Both the cached Google access token and the downstream OAuth session state (registered clients, tokens) live in memory and are lost on redeploy or restart -- you'll just need to reconnect the connector afterwards (the Google refresh token itself is unaffected; it's re-exchanged for a fresh access token automatically). Acceptable trade-off for a low-traffic personal instance; see the TDD.

• fly.toml's [http_service] is configured to stay always-on (not scaled to zero) for exactly that reason -- a stop/start cycle would otherwise force reconnection too.

Development

npm install
npm run dev:stdio      # run src/stdio.ts directly with tsx
npm run dev:http       # run src/http.ts directly with tsx
npm run typecheck
npm run lint            # biome check
npm run lint:fix
npm test
npm run build           # bundles dist/stdio.js and dist/http.js with tsup

See docs/architecture.md for the repo layout and request-flow details.

License

MIT -- see LICENSE.