fitbit-google-health-mcp

Read-only MCP access to Fitbit-synced health data through Google Health API v4. This is not a direct Fitbit Web API integration. The server is MCP-only: there is no dashboard, database, health-data cache, write operation, or arbitrary HTTP tool.

It isolates unavailable metrics so one Google Health API limitation does not fail an entire request.

Setup

1. Create a Google Cloud project and enable the Google Health API.

2. Configure an OAuth consent screen and add your Google/Fitbit account as a test user.

3. Create a Web application OAuth client with this exact redirect URI:

   http://127.0.0.1:42813/oauth/callback

4. Copy .env.example to .env and fill in the client ID and secret. Never commit .env or OAuth tokens.

5. Install and build:

   pnpm install
   pnpm build
   

6. Authorize the account:

   set -a; source .env; set +a
   pnpm auth
   

7. Add the server to your MCP client using the built dist/src/index.js and the same environment variables. run.sh is a convenient stdio launcher.

The Fitbit Air must already be paired to the Fitbit mobile app. Fitbit devices sync through the Fitbit app; they do not expose a direct third-party Bluetooth path. Open the Fitbit app and sync before asking the MCP for new readings.

Tools

• get_data_source_info: provider, data path, read-only boundary, and limitations. Call this first when interpreting results.
• list_available_metrics: the broad Google Health v4 catalog implemented by this server.
• get_metrics: query any supported data types over a range, raw or daily aggregate, with source filtering.
• get_daily_summary: common daily metrics in one call.
• get_profile, get_devices, get_settings: connected account metadata.
• get_recent_metrics: recent-range queries with per-metric failure isolation.
• get_health_snapshot: compact current-day summary.
• get_trends: numeric averages, ranges, and changes.
• get_sleep_summary: normalized sleep sessions and stages.
• get_sync_status: account, devices, and recent-data availability.
• compare_periods: compare the current period with the prior period.
• get_data_quality: report coverage, missing data, sources, and API limitations.
• get_activity_summary: normalized movement and activity trends.
• get_recovery_summary: informational sleep, heart, oxygen, and respiration summary.
• get_body_metrics: normalized weight, body-fat, temperature, height, and glucose data.

The server requests read-only scopes only. It does not expose write, delete, webhook, or arbitrary HTTP tools.

Multi-source data

Every metric query and summary accepts:

• source: FITBIT, HEALTH_KIT, or all (default).
• source_priority: source precedence when same-time records disagree; defaults to Fitbit first, then HealthKit.
• deduplicate: remove exact duplicates and resolve same-time cross-source conflicts (default: true).

Responses retain raw records and add sourceAnalysis metadata containing source coverage, returned versus raw record counts, duplicates removed, and conflicts detected. Source filtering is most precise with raw data; rollup-only Google Health types may report unknown coverage because the rollup response does not carry source metadata.

Development

pnpm install
pnpm check

The project requires Node 20+ and pnpm. Run pnpm auth once to create the local OAuth token, then use pnpm start or ./run.sh with your MCP client.

Privacy and security

This server handles sensitive health data. Keep OAuth credentials private, use a restricted Google Cloud test-user list, and never paste token contents into issues or logs. Tokens default to ~/.config/fitbit-mcp/tokens.json (or $XDG_CONFIG_HOME/fitbit-mcp/tokens.json) with owner-only permissions. Set FITBIT_MCP_TOKEN_PATH for another secure location.

The server does not diagnose conditions or provide medical advice. Metric availability varies; unavailable results are missing data, not zero.

Notes

Metric presence varies by Fitbit device, account, country, permissions, and recent sync. Google Health API query ranges are constrained: heart-rate, active-minutes, total-calories, and heart-rate-zone queries should be kept to 14 days or less; most other types support up to 90 days per request. Historical data can be fetched in multiple ranges.

Recent and summary tools accept an IANA timezone such as America/Detroit. Raw API records are preserved, while summary tools add normalized distance, weight, calorie, and sleep-duration fields. Missing data is reported explicitly and is never interpreted as zero.

OpenClaw

Register the local stdio server without a hardcoded tool allowlist so newly added read-only tools become available automatically:

openclaw mcp add fitbit-google-health \
  --command /Users/rithvik/fitbit-mcp/run.sh \
  --cwd /Users/rithvik/fitbit-mcp
openclaw mcp doctor fitbit-google-health --probe
openclaw mcp reload

Use an OpenClaw tool filter only when you intentionally want to restrict the agent. The get_data_source_info tool is the canonical way for an agent to understand that this server uses Google Health API v4 and may contain Fitbit-synced records rather than direct Fitbit Web API records.