# 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:

   ```bash
   pnpm install
   pnpm build
   ```

6. Authorize the account:

   ```bash
   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

```bash
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:

```bash
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.