Skip to main content
Glama
Sign In
fitbit-mcp

fitbit-mcp

by detarus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

fitbit-mcp

Local Fitbit MCP via Google Health API, with read tools, reviewed meal/water writes, and shared skills for Codex and Claude Code.

Status: alpha.4 prerelease; real-account validation pending. No npm registry publication. Validation and tested package artifacts. Planned work is tracked in ROADMAP.md.

Try it

Node.js 24 LTS and pnpm 10.20.0 are required.

git clone https://github.com/detarus/fitbit-mcp.git
cd fitbit-mcp
pnpm install --frozen-lockfile
pnpm check
node dist/cli.js demo-check
node dist/cli.js report --demo --start 2026-10-01 --end 2026-10-08
node dist/cli.js recovery --demo --date 2026-10-17

Testing on Mac: Russian · English · Summary semantics · Recovery model · Operations

Demo uses synthetic records and makes no Google requests. Live setup needs your own Google Cloud Desktop OAuth client and browser consent. Keep credentials outside the repository.

Related MCP server: Fitbit Health MCP Server

Implemented alpha surface

  • Google OAuth with loopback callback, state and PKCE; explicit terminal authorization.

  • Status/device metadata, bounded raw reads, daily wearable activity rollups, normalized summaries and code-calculated period comparisons.

  • Local immutable meal/water previews, explicit commits, per-item read-back and duplicate protection for the same operation.

  • Stable write IDs, read-only reconciliation of interrupted writes/deletes, linked non-atomic meal/water corrections.

  • Personal-relative recovery model with a 28-day baseline and explicit factors; SpO2, respiration and skin-temperature deltas.

  • One-command MCP plus shared skills installation for Codex/Claude Code; plugin manifests also included.

  • Claude Desktop local configuration installer and shared MCP prompts; setup.

  • CI for synthetic checks on macOS, Windows and Linux. Real OAuth/client verification is tracked separately.

Actual API compatibility, data coverage and app presentation still need live validation. Normalized summaries expose activity/sleep/heart/vitals with explicit coverage. Our recovery heuristic is not Fitbit Daily Readiness or a clinically validated score.

For release installation, client setup, updating and removal see installation and the compatibility matrix.

Meal workflow

Photo or text in a compatible AI client → proposed dishes, portions and approximate macros → local preview → explicit save request → Google Health records → read-back and diary verification.

Values describe the whole dish portion. Photos cannot establish exact weight or hidden ingredients. Fitbit Air has no screen; nutrition records belong in Google Health and the conversation. For ordinary chats see the client/plan matrix; Claude Desktop now has a local installer. Web/mobile remote connections remain a later milestone.

Privacy

Tokens and write journals stay in a per-user directory with POSIX permissions or Windows ACLs. They are not encrypted by this application. Tool results may be sent to the AI client's provider. No credentials or private account data are needed in CI.

Disconnect removes local tokens; revoke the Google grant separately. Journals retain meal data for reconciliation. Never attach them or meal photos to public issues.

Project

This repository focuses on Fitbit. A future universal tracker integration will be a separate project.

See architecture, research, contributing, security and the maintained roadmap.

Copyright 2026 Dmitrii Tareev and fitbit-mcp contributors. Apache-2.0. Independent project; not affiliated with Google or Fitbit.

Available Tools

13 tools
fitbit_activityA
Read-only

Daily server-reconciled wearable activity for 1–14 civil days (end exclusive). Returns raw rollup fields; missing values are not zero. A failed domain is explicit.

Inputs: endDate (required), startDate (required).

fitbit_cancel_draftA
DestructiveIdempotent

Cancel an untouched local preview; does not delete Google records.

Inputs: operationId (required).

fitbit_commitA
DestructiveIdempotent

Save an existing reviewed preview after explicit user intent. Reusing its operation ID never blindly replays an uncertain item. Return per-item states; only verified means read-back succeeded.

Inputs: confirm (required), operationId (required).

fitbit_compareA
Read-only

Compare equal calendar windows using code-calculated paired-day means and coverage. Defaults to the preceding window of the same length. No medical or recovery score is invented.

Inputs: endDate (required), startDate (required), domains, previousEndDate, +1 more.

fitbit_devicesB
Read-only

Read paired device metadata.

Inputs: no named parameters.

fitbit_operationB
Read-only

Inspect the persisted state of a meal/water operation. Never silently resubmit uncertain writes.

Inputs: operationId (required).

fitbit_preview_mealA
Idempotent

Create a local meal draft ONLY. Values apply to the whole dish portion, not per 100g. Review assumptions, portions, date/offset and all K/P/F/C values before saving. Photo estimates are approximate.

Inputs: at (required), dishes (required), mealType (required), requestId (required).

fitbit_preview_waterA
Idempotent

Create a local water draft ONLY. Review volume and date/time with offset before saving.

Inputs: at (required), requestId (required), milliliters (required).

fitbit_readA
Read-only

Read 1–14 civil calendar days, endDate exclusive. Sleep is grouped by wake date. Raw samples may overlap: do not sum them as daily totals. At most 500 points per call; if incomplete, pass nextPageToken as pageToken with the same type/dates to continue.

Inputs: type (required), endDate (required), startDate (required), pageToken.

fitbit_removeA
DestructiveIdempotent

Remove only the known Google records created by this operation, after explicit user intent. Blocks uncertain records; verifies deletion. To correct manual-food macros, remove old records then review and save a new preview; this is not atomic.

Inputs: confirm (required), operationId (required).

fitbit_request_idA
Read-only

Generate a UUID for one new meal/water draft. Reuse the same ID on retries; use a new ID for a new occurrence.

Inputs: no named parameters.

fitbit_statusB
Read-only

Local connection metadata and implemented types. Declared support is not proof of data availability on this device. Does not return credentials.

Inputs: no named parameters.

fitbit_summaryA
Read-only

Normalized daily health metrics and period statistics for 1–14 civil days, end exclusive. Reconciles wearable sources; sleep is grouped by wake date. Missing, conflicting, partial and failed metrics remain explicit. Totals are null unless all requested days are observed.

Inputs: endDate (required), startDate (required), domains.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have distinct roles: preview_meal vs preview_water differ by resource, and commit/cancel/remove/operation form a clear write lifecycle. However, the read trio (fitbit_read, fitbit_activity, fitbit_summary) all return day-based health data and require careful reading of descriptions to distinguish raw vs rollup vs normalized.

    Naming Consistency4/5

    All tools share a consistent fitbit_ snake_case prefix, which is highly predictable. Minor deviation: most names are verb-led (read, compare, preview_meal) while a few are noun-led (status, devices, operation), but the pattern remains readable and coherent.

    Tool Count5/5

    13 tools sits squarely in the well-scoped 3-15 range. Each tool earns its place, covering read, compare, and a full meal/water draft lifecycle without obvious redundancy.

    Completeness4/5

    The surface covers reads (raw/activity/summary), comparison, device/status metadata, and a full draft-commit-cancel-remove write lifecycle with operation inspection. The main gap is no in-place update for corrections, handled non-atomically via remove+new preview, which is a minor workaround.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Google Health MCP

      davidmosiah
      A
      license
      B
      quality
      B
      maintenance
      A local-first MCP server that enables AI agents to read user-authorized Google Health API v4 data from Fitbit, Pixel Watch, and partners via OAuth, with tokens never leaving the machine.
      26
      850 npm
      81
      MIT

    • Fitbit Health MCP Server

      Ma1ndo26rc
      A
      license
      A
      quality
      D
      maintenance
      Provides read-only access to Fitbit health data (sleep, steps, heart rate, HRV) via local sync with Google Health API. Enables querying daily health summaries and trends through MCP tools without uploading data to cloud.
      6
      MIT

    • fitbit-google-health-mcp

      rickygarim
      A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP access to Fitbit-synced health data through Google Health API v4. Provides tools for metrics, summaries, trends, and data quality without write or arbitrary HTTP operations.
      MIT

    • google-health-mcp

      metacurb
      A
      license
      A
      quality
      C
      maintenance
      Provides local, read-only MCP access to Google Health API v4, enabling users to query recorded workouts, heart-rate samples, and related health data through natural language in an MCP client.
      3
      55 npm
      MIT