fitbit-mcp

MCP server for the Fitbit Web API with OAuth PKCE, local SQLite cache, and trend analysis.

Designed for Claude Code and other MCP clients. Syncs your Fitbit data to a local database for fast, offline queries - no API calls needed after the initial sync.

Features

• OAuth 2.0 PKCE - Secure auth flow, no client secret needed
• Local SQLite cache - Sync once, query instantly
• Incremental sync - Only fetches new data since last sync
• 17 MCP tools - Sync, query (12 cached data types + devices/lifetime/goals), and trend analysis
• Live mode - Bypass cache and query the API directly
• CLI - Auth setup, sync, and JSON import from the command line
• Rate limit handling - Automatic retry on 429 responses

Data types

Tool	Data
fitbit_get_heart_rate	Resting HR, HR zones
fitbit_get_activity	Steps, calories, active minutes, distance
fitbit_get_exercises	Exercise sessions (name, duration, HR, calories)
fitbit_get_sleep	Duration, efficiency, sleep stages
fitbit_get_weight	Weight, BMI, body fat %
fitbit_get_spo2	Blood oxygen saturation (avg/min/max)
fitbit_get_hrv	Heart rate variability (RMSSD)
fitbit_get_azm	Active Zone Minutes with per-zone breakdown
fitbit_get_breathing_rate	Nightly breaths per minute
fitbit_get_temperature	Nightly skin temperature variation (degrees C from baseline)
fitbit_get_cardio_fitness	VO2 Max / Cardio Fitness Score
fitbit_get_food_log	Daily food calories + water intake
fitbit_get_devices	Paired devices, battery level, last sync (live)
fitbit_get_lifetime_stats	All-time totals and personal best records (live)
fitbit_get_goals	User-set daily/weekly activity goals (live)
fitbit_trends	Aggregated averages (weekly/monthly/quarterly)

Requirements

• Python 3.13+
• A Fitbit developer account with a registered personal app

Setup

1. Install

pip install .

Or for development:

pip install -e ".[dev]"

2. Register a Fitbit app

1. Go to dev.fitbit.com/apps and create a new app
2. Set OAuth 2.0 Application Type to Personal
3. Set Redirect URL to http://localhost:8080
4. Note your Client ID (you won't need the client secret - PKCE doesn't use one)

3. Authenticate

fitbit-mcp auth

This opens your browser for Fitbit login, exchanges the auth code via PKCE, and saves tokens locally.

Tokens 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.

4. Register with Claude Code

claude mcp add -s user fitbit -- fitbit-mcp

5. First sync (optional)

Query tools auto-sync on first use, so you can skip this step. To pre-populate the cache or sync a longer history, run:

fitbit-mcp sync --days 30

CLI usage

fitbit-mcp              Start the MCP server (stdio transport)
fitbit-mcp auth         Interactive OAuth setup
fitbit-mcp sync         Sync data to local cache
  --days N              Days of history for first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all)
fitbit-mcp import       Import existing JSON data files
  --data-dir PATH       Directory containing JSON files

MCP tool reference

Query tools auto-sync on the first query of each day per data type. Use live=True to bypass the cache entirely and fetch directly from the API.

All query tools accept these common parameters:

• start_date - Start date as YYYY-MM-DD, YYYY-MM, or 30d (relative). Default: last 30 days.
• end_date - End date as YYYY-MM-DD. Default: today.
• live - If true, fetch from Fitbit API instead of cache (bypasses auto-sync).

fitbit_get_exercises also accepts:

• exercise_type - Filter by activity name (case-insensitive substring match), e.g. "cycling", "walk", "run". Default: all types.

fitbit_sync

Syncs 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.

• 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.
• days - Days of history for first sync (default: 30). Subsequent syncs are incremental.

fitbit_trends

Aggregated trend analysis from cached data.

• data_type - What to analyse: heart_rate, activity, exercises, sleep, weight, spo2, hrv, azm, breathing_rate, skin_temperature, cardio_fitness, food_log. Default: activity.
• period - Aggregation: weekly, monthly, quarterly. Default: monthly.
• start_date - Start date. Default: last 12 months (365 days).
• end_date - End date. Default: today.
• 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.

OAuth scopes

The following Fitbit API scopes are requested during setup:

Scope	Data accessed
activity	Steps, calories, active minutes, distance, AZM, lifetime stats, goals
heartrate	Resting HR, HR zones, HRV
sleep	Sleep duration and stages
weight	Weight, BMI, body fat %
oxygen_saturation	SpO2 (blood oxygen)
profile	User profile (user ID, display name)
respiratory_rate	Nightly breathing rate
temperature	Skin temperature variation
cardio_fitness	VO2 Max / Cardio Fitness Score
nutrition	Daily food calorie and water log
location	GPS data on logged exercises
settings	Paired devices (battery, last sync)

These 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.

Configuration

Paths are overridable via environment variables:

Variable	Default	Description
FITBIT_MCP_CONFIG_DIR	~/.config/fitbit-mcp/	Directory for OAuth credentials
FITBIT_MCP_DB_PATH	~/.local/share/fitbit-mcp/fitbit.db	SQLite database path

Rate limits

The Fitbit API allows 150 requests per hour. The sync tool handles rate limits automatically, but be aware:

• Activity and food log syncs use 1 API call per day (no date-range endpoint available)
• A 30-day initial sync of either uses ~30 of your 150/hour quota
• Heart rate, sleep, weight, SpO2, HRV, AZM, breathing rate, skin temperature, and cardio fitness use date-range endpoints and are much more efficient

Use live=False (the default) to query from cache and avoid API calls entirely.

Data safety

This project includes a pre-commit hook (scripts/check-no-data.sh) that prevents accidentally committing:

• Database files (*.db, *.db-journal, *.db-wal)
• Config/credentials (config/*.json)
• Large files (>100KB)

Install it after cloning:

cp scripts/check-no-data.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Importing existing data

If you have existing Fitbit data as JSON files (e.g. from a previous export or script), you can bulk-import them:

fitbit-mcp import --data-dir /path/to/json/files/

Expected 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.

Contributing

See CONTRIBUTING.md for development setup, the test workflow, and the pre-commit hook. Changes are tracked in CHANGELOG.md.

License

GPL-3.0-or-later