{"id":50987040,"url":"https://github.com/partymola/fitbit-mcp","last_synced_at":"2026-06-19T20:31:21.417Z","repository":{"id":351881488,"uuid":"1203299735","full_name":"partymola/fitbit-mcp","owner":"partymola","description":"MCP server for the Fitbit Web API with OAuth PKCE, local SQLite cache, and trend analysis","archived":false,"fork":false,"pushed_at":"2026-05-22T01:47:08.000Z","size":184,"stargazers_count":0,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T10:57:32.754Z","etag":null,"topics":["claude","fitbit","fitbit-api","mcp","mcp-server","model-context-protocol","oauth","quantified-self"],"latest_commit_sha":null,"homepage":"https://modelcontextprotocol.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/partymola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-06T23:14:07.000Z","updated_at":"2026-05-22T01:47:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/partymola/fitbit-mcp","commit_stats":null,"previous_names":["partymola/fitbit-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/partymola/fitbit-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partymola%2Ffitbit-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partymola%2Ffitbit-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partymola%2Ffitbit-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partymola%2Ffitbit-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/partymola","download_url":"https://codeload.github.com/partymola/fitbit-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/partymola%2Ffitbit-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34547787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","fitbit","fitbit-api","mcp","mcp-server","model-context-protocol","oauth","quantified-self"],"created_at":"2026-06-19T20:31:20.885Z","updated_at":"2026-06-19T20:31:21.412Z","avatar_url":"https://github.com/partymola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fitbit-mcp\n\n[![CI](https://github.com/partymola/fitbit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/partymola/fitbit-mcp/actions/workflows/ci.yml)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![Glama MCP Server](https://glama.ai/mcp/servers/partymola/fitbit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/partymola/fitbit-mcp)\n\nMCP server for the Fitbit Web API with OAuth PKCE, local SQLite cache, and trend analysis.\n\nDesigned for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and other [MCP](https://modelcontextprotocol.io/) clients. Syncs your Fitbit data to a local database for fast, offline queries - no API calls needed after the initial sync.\n\n## Features\n\n- **OAuth 2.0 PKCE** - Secure auth flow, no client secret needed\n- **Local SQLite cache** - Sync once, query instantly\n- **Incremental sync** - Only fetches new data since last sync\n- **17 MCP tools** - Sync, query (12 cached data types + devices/lifetime/goals), and trend analysis\n- **Live mode** - Bypass cache and query the API directly\n- **CLI** - Auth setup, sync, and JSON import from the command line\n- **Rate limit handling** - Automatic retry on 429 responses\n\n## Data types\n\n| Tool | Data |\n|------|------|\n| `fitbit_get_heart_rate` | Resting HR, HR zones |\n| `fitbit_get_activity` | Steps, calories, active minutes, distance |\n| `fitbit_get_exercises` | Exercise sessions (name, duration, HR, calories) |\n| `fitbit_get_sleep` | Duration, efficiency, sleep stages |\n| `fitbit_get_weight` | Weight, BMI, body fat % |\n| `fitbit_get_spo2` | Blood oxygen saturation (avg/min/max) |\n| `fitbit_get_hrv` | Heart rate variability (RMSSD) |\n| `fitbit_get_azm` | Active Zone Minutes with per-zone breakdown |\n| `fitbit_get_breathing_rate` | Nightly breaths per minute |\n| `fitbit_get_temperature` | Nightly skin temperature variation (degrees C from baseline) |\n| `fitbit_get_cardio_fitness` | VO2 Max / Cardio Fitness Score |\n| `fitbit_get_food_log` | Daily food calories + water intake |\n| `fitbit_get_devices` | Paired devices, battery level, last sync (live) |\n| `fitbit_get_lifetime_stats` | All-time totals and personal best records (live) |\n| `fitbit_get_goals` | User-set daily/weekly activity goals (live) |\n| `fitbit_trends` | Aggregated averages (weekly/monthly/quarterly) |\n\n## Requirements\n\n- Python 3.13+\n- A [Fitbit developer account](https://dev.fitbit.com/apps) with a registered personal app\n\n## Setup\n\n### 1. Install\n\n```bash\npip install .\n```\n\nOr for development:\n\n```bash\npip install -e \".[dev]\"\n```\n\n### 2. Register a Fitbit app\n\n1. Go to [dev.fitbit.com/apps](https://dev.fitbit.com/apps) and create a new app\n2. Set **OAuth 2.0 Application Type** to **Personal**\n3. Set **Redirect URL** to `http://localhost:8080`\n4. Note your **Client ID** (you won't need the client secret - PKCE doesn't use one)\n\n### 3. Authenticate\n\n```bash\nfitbit-mcp auth\n```\n\nThis opens your browser for Fitbit login, exchanges the auth code via PKCE, and saves tokens locally.\n\nTokens are stored in `~/.config/fitbit-mcp/fitbit_tokens.json` with 0600 permissions. Access tokens expire in 8 hours and are refreshed automatically. Refresh tokens expire after 90 days of inactivity.\n\n### 4. Register with Claude Code\n\n```bash\nclaude mcp add -s user fitbit -- fitbit-mcp\n```\n\n### 5. First sync (optional)\n\nQuery tools auto-sync on first use, so you can skip this step. To pre-populate\nthe cache or sync a longer history, run:\n\n```bash\nfitbit-mcp sync --days 30\n```\n\n## CLI usage\n\n```\nfitbit-mcp              Start the MCP server (stdio transport)\nfitbit-mcp -V, --version  Print the installed package version\nfitbit-mcp auth         Interactive OAuth setup\nfitbit-mcp sync         Sync data to local cache\n  --days N              Days of history for first sync (default: 30)\n  --types TYPE,...      Data types to sync (default: all)\nfitbit-mcp import       Import existing JSON data files\n  --data-dir PATH       Directory containing JSON files\n```\n\n## MCP tool reference\n\nQuery tools auto-sync on the first query of each day per data type. Use `live=True`\nto bypass the cache entirely and fetch directly from the API.\n\nAll query tools accept these common parameters:\n\n- `start_date` - Start date as `YYYY-MM-DD`, `YYYY-MM`, or `30d` (relative). Default: last 30 days.\n- `end_date` - End date as `YYYY-MM-DD`. Default: today.\n- `live` - If true, fetch from Fitbit API instead of cache (bypasses auto-sync).\n\n`fitbit_get_exercises` also accepts:\n\n- `exercise_type` - Filter by activity name (case-insensitive substring match), e.g. `\"cycling\"`, `\"walk\"`, `\"run\"`. Default: all types.\n\n### fitbit_sync\n\nSyncs data from the Fitbit API to the local SQLite cache. Query tools call this automatically on first use of the day, so explicit calls are only needed for longer history or forced refresh.\n\n- `data_types` - What to sync: `all`, `heart_rate`, `activity`, `exercises`, `sleep`, `weight`, `spo2`, `hrv`, `azm`, `breathing_rate`, `skin_temperature`, `cardio_fitness`, `food_log`. Comma-separated. Default: `all`.\n- `days` - Days of history for first sync (default: 30). Subsequent syncs are incremental.\n\n### fitbit_trends\n\nAggregated trend analysis from cached data.\n\n- `data_type` - What to analyse: `heart_rate`, `activity`, `exercises`, `sleep`, `weight`, `spo2`, `hrv`, `azm`, `breathing_rate`, `skin_temperature`, `cardio_fitness`, `food_log`. Default: `activity`.\n- `period` - Aggregation: `weekly`, `monthly`, `quarterly`. Default: `monthly`.\n- `start_date` - Start date. Default: last 12 months (365 days).\n- `end_date` - End date. Default: today.\n- `compare` - Compare two periods: `last_30d vs previous_30d`, `2026-03 vs 2026-02`, `2026-Q1 vs 2025-Q4`. When set, `period`/`start_date`/`end_date` are ignored.\n\n## OAuth scopes\n\nThe following Fitbit API scopes are requested during setup:\n\n| Scope | Data accessed |\n|-------|--------------|\n| `activity` | Steps, calories, active minutes, distance, AZM, lifetime stats, goals |\n| `heartrate` | Resting HR, HR zones, HRV |\n| `sleep` | Sleep duration and stages |\n| `weight` | Weight, BMI, body fat % |\n| `oxygen_saturation` | SpO2 (blood oxygen) |\n| `profile` | User profile (user ID, display name) |\n| `respiratory_rate` | Nightly breathing rate |\n| `temperature` | Skin temperature variation |\n| `cardio_fitness` | VO2 Max / Cardio Fitness Score |\n| `nutrition` | Daily food calorie and water log |\n| `location` | GPS data on logged exercises |\n| `settings` | Paired devices (battery, last sync) |\n\nThese are the scopes needed for all tools. If you only need a subset, edit `FITBIT_SCOPES` in `config.py` before setup. After upgrading from a smaller scope set, re-run `fitbit-mcp auth` to re-authorise.\n\n## Configuration\n\nPaths are overridable via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `FITBIT_MCP_CONFIG_DIR` | `~/.config/fitbit-mcp/` | Directory for OAuth credentials |\n| `FITBIT_MCP_DB_PATH` | `~/.local/share/fitbit-mcp/fitbit.db` | SQLite database path |\n| `FITBIT_MCP_OFFLINE` | unset | If truthy (`1`, `true`, `yes`, `on`), run as a cache-only reader: no credentials required, no live API calls. See below. |\n\n### Offline / cache-only mode\n\nBy default the server auto-syncs on demand, so query tools fetch fresh data\nwithout a cron job. Set `FITBIT_MCP_OFFLINE=1` to run as a pure cache reader\ninstead:\n\n- No Fitbit credentials are required - the server never touches the token file.\n- No live API calls are made. Auto-sync is disabled, and `live=True`, the\n  live-only tools (`fitbit_get_devices`, `fitbit_get_lifetime_stats`,\n  `fitbit_get_goals`), and `fitbit_sync` return a clear \"offline mode\" message\n  instead of calling the API.\n- Query tools serve whatever is in the local SQLite cache. Responses are tagged\n  with `\"offline_mode\": true`.\n\nTypical uses:\n\n- **Multi-device setups** - one host runs `fitbit-mcp sync` (via cron/systemd)\n  against a shared database; other hosts set `FITBIT_MCP_OFFLINE=1` and point\n  `FITBIT_MCP_DB_PATH` at the same cache, and only read. This keeps the Fitbit\n  OAuth token (single-use, rotating) owned by exactly one host, avoiding refresh\n  collisions.\n- **CI and privacy** - run queries with no network access and no credentials.\n\nKeeping the cache fresh is then the syncing host's job. Unset\n`FITBIT_MCP_OFFLINE` to return to on-demand auto-sync.\n\n## Rate limits\n\nThe Fitbit API allows 150 requests per hour. The sync tool handles rate limits automatically, but be aware:\n\n- Activity and food log syncs use 1 API call per day (no date-range endpoint available)\n- A 30-day initial sync of either uses ~30 of your 150/hour quota\n- Heart rate, sleep, weight, SpO2, HRV, AZM, breathing rate, skin temperature, and cardio fitness use date-range endpoints and are much more efficient\n\nUse `live=False` (the default) to query from cache and avoid API calls entirely.\n\n## Data safety\n\nThis project includes a pre-commit hook (`scripts/check-no-data.sh`) that prevents accidentally committing:\n\n- Database files (`*.db`, `*.db-journal`, `*.db-wal`)\n- Config/credentials (`config/*.json`)\n- Large files (\u003e100KB)\n\nInstall it after cloning:\n\n```bash\ncp scripts/check-no-data.sh .git/hooks/pre-commit\nchmod +x .git/hooks/pre-commit\n```\n\n## Importing existing data\n\nIf you have existing Fitbit data as JSON files (e.g. from a previous export or script), you can bulk-import them:\n\n```bash\nfitbit-mcp import --data-dir /path/to/json/files/\n```\n\nExpected file names: `heart_rate.json`, `activity.json`, `exercises.json`, `sleep.json`, `weight.json`, `spo2.json`, `hrv.json`. See `src/fitbit_mcp/importer.py` for the expected JSON format.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the test workflow, and the pre-commit hook. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\n[GPL-3.0-or-later](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpartymola%2Ffitbit-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpartymola%2Ffitbit-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpartymola%2Ffitbit-mcp/lists"}