io.github.davidmosiah/fitbitmcp
Privacy-first, unofficial Fitbit MCP server for AI health, sleep, activity and heart-rate agents.
Open source Open in the app JSON README (API)
About
Privacy-first, unofficial Fitbit MCP server for AI health, sleep, activity and heart-rate agents.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- davidmosiah
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.4.5
- Stars
- 4
- Forks
- 1
- Last push
- 2026-08-29T10:27:25Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.davidmosiah/fitbitmcp
README
<!-- delx-wellness header v2 -->
<h1 align="center">Fitbit MCP</h1>
<div align="center">
<img src="assets/banner.png" alt="Fitbit MCP — Fitbit MCP for AI agents" width="85%" />
</div>
<h3 align="center">
Give your AI agent your Fitbit activity, sleep, heart and HRV data — locally.<br>
Local-first MCP server — <strong>tokens never leave your machine</strong>.
</h3>
<p align="center">
<a href="https://www.npmjs.com/package/fitbit-mcp-unofficial"><img src="https://img.shields.io/npm/v/fitbit-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm version" /></a>
<a href="https://www.npmjs.com/package/fitbit-mcp-unofficial"><img src="https://img.shields.io/npm/dm/fitbit-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="License MIT" /></a>
<a href="https://wellness.delx.ai/connectors/fitbit"><img src="https://img.shields.io/badge/SITE-wellness.delx.ai-0EA5A3?style=for-the-badge&labelColor=0F172A" alt="Site" /></a>
</p>
<p align="center">
<a href="https://github.com/davidmosiah/fitbit-mcp/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub stars" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="Built for MCP" /></a>
<a href="https://github.com/davidmosiah/delx-wellness-hermes"><img src="https://img.shields.io/badge/HERMES-one--command_setup-10B981?style=for-the-badge&labelColor=0F172A" alt="Hermes one-command setup" /></a>
<a href="https://github.com/davidmosiah/delx-wellness"><img src="https://img.shields.io/badge/Fitbit-00B0B9?style=for-the-badge&labelColor=0F172A&logoColor=white&logo=fitbit&logoColor=white" alt="Fitbit" /></a>
</p>
> ⚡ **One-command install** with [Delx Wellness for Hermes](https://github.com/davidmosiah/delx-wellness-hermes):
> `npx -y delx-wellness-hermes setup` — preconfigures this connector and the other 8 in a dedicated Hermes profile.
>
> Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.
---
## HTTP (v2 stateless)
Default is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:
```bash
npx -y fitbit-mcp-unofficial --http
# GET http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp (sessionless)
```
Env: `FITBIT_MCP_HOST`, `FITBIT_MCP_PORT`, `FITBIT_MCP_TRANSPORT=http`.
<!-- /delx-wellness header v2 -->
**Local-first MCP server that connects AI agents to your Fitbit activity, sleep, heart-rate, HRV, SpO2 and weight data.**
> **Unofficial project.** Not affiliated with, endorsed by or supported by Fitbit or Google. Use this only with your own Fitbit account and in line with the Fitbit Web API terms.
> **Platform migration risk:** Fitbit is migrating to the Google Health API. OAuth, base URL, scopes and reconnection flows may change in 2026. Treat any breakage as platform drift and check the [Fitbit Web API docs](https://dev.fitbit.com/build/reference/web-api/) before reporting it as a bug.
Built by [David Mosiah](https://github.com/davidmosiah) for people who use Claude, Cursor, Hermes, OpenClaw or other MCP-compatible agents to think about activity, sleep and heart context — without copy-pasting numbers from the Fitbit app.
Part of [Delx Wellness](https://github.com/davidmosiah/delx-wellness), a registry of local-first wellness MCP connectors.
> If this connector helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.
## Why this exists
Fitbit (now under Google) has years of wearable data — daily activity, sleep stages, intraday heart-rate, HRV, SpO2, breathing rate, weight, food and water logs. But its API uses OAuth 2.0 with per-scope authorization and intraday access that varies by app, and the platform is mid-migration to the Google Health API.
This package handles the OAuth dance locally, normalizes responses, and exposes Fitbit through the Model Context Protocol. Tokens never leave your machine. Privacy-mode defaults keep raw payloads opt-in.
## Setup in 60 seconds
You'll need a Fitbit app ([create one here](https://dev.fitbit.com/apps)) with redirect URI `http://127.0.0.1:3000/callback`.
```bash
npx -y fitbit-mcp-unofficial setup # interactive: paste client id + secret
npx -y fitbit-mcp-unofficial auth # opens browser, captures the OAuth code
npx -y fitbit-mcp-unofficial doctor # verifies you're ready
```
Recommended scopes:
```text
activity heartrate profile settings sleep weight nutrition
```
Then add this to your MCP client config:
```json
{
"mcpServers": {
"fitbit": {
"command": "npx",
"args": ["-y", "fitbit-mcp-unofficial"]
}
}
}
```
For Claude Desktop, run `setup --client claude` and the snippet is written for you.
## Try it with your agent
Three things to ask first:
```text
Use fitbit_connection_status to check setup, then run fitbit_daily_summary.
Give me a 5-line operating brief for today.
```
```text
Call fitbit_weekly_summary with response_format=json. Identify my biggest
sleep/activity bottleneck and give me a next-week plan.
```
```text
Use the fitbit_intraday_investigation prompt for date=today, detail_level=1min.
Don't claim anything Fitbit can't actually prove.
```
## Data availability
This package uses the official Fitbit Web API. When this README says `raw`, it means the upstream Fitbit JSON for a supported endpoint — not raw device sensor streams.
| Data | Available | Notes |
|---|:---:|---|
| Daily activity (steps, calories, distance, zones) | ✓ | Standard activity summaries |
| Activity logs | ✓ | Logged workouts |
| Sleep + sleep stages | ✓ | When Fitbit returns stage data |
| Resting heart rate + daily heart-rate zones | ✓ | All scored days |
| Intraday heart-rate samples | conditional | Only when the Fitbit app/API access permits intraday |
| HRV (overnight) | ✓ | When supported by device/account |
| SpO2 (overnight) | ✓ | When supported by device/account |
| Breathing rate | ✓ | When supported by device/account |
| Weight + body composition | ✓ | When logged |
| Food + water logs | ✓ | When logged |
| Continuous device telemetry | — | Not exposed by Fitbit's public API |
## Tools
**Start with these:**
- `fitbit_connection_status` — verify local setup before calling Fitbit
- `fitbit_data_inventory` — inventory supported data domains, scopes, privacy modes and recommended first calls without calling Fitbit APIs.
- `fitbit_daily_summary` — readiness, activity, sleep and heart context for today
- `fitbit_weekly_summary` — scorecard, comparison vs prior week, next-week plan
**Auth & diagnostics**
- `fitbit_capabilities`, `fitbit_agent_manifest`, `fitbit_privacy_audit`, `fitbit_cache_status`
- `fitbit_get_auth_url`, `fitbit_exchange_code`, `fitbit_revoke_access`
**Profile & devices**
- `fitbit_get_profile`, `fitbit_list_devices`
**Activity**
- `fitbit_get_activity_day`, `fitbit_list_activities`, `fitbit_get_activity`
- List calls accept either `after` or `before`, matching Fitbit's mutually exclusive cursor contract. Offset ISO inputs retain their written calendar date and invalid cursors fail before HTTP.
**Sleep**
- `fitbit_get_sleep_day`, `fitbit_list_sleep`
**Heart & physiology** (each takes a `date`)
- `fitbit_get_heart_day`, `fitbit_heart_series`, `fitbit_get_heart_intraday`
- `fitbit_get_hrv_day`, `fitbit_get_spo2_day`, `fitbit_get_breathing_rate_day`
**Body & nutrition** (each takes a `date`)
- `fitbit_get_weight_day`, `fitbit_get_food_day`, `fitbit_get_water_day`
## Prompts
- `fitbit_daily_checkin` — practical daily health and activity check-in
- `fitbit_weekly_review` — review trends across activity, sleep and heart context
- `fitbit_intraday_investigation` — investigate one day's intraday heart-rate samples
## Resources
- `fitbit://capabilities`, `fitbit://agent-manifest`
- `fitbit://summary/daily`, `fitbit://summary/weekly`
## Privacy & security
- OAuth tokens are stored in `~/.fitbit-mcp/tokens.json` with `0600` permissions and are never returned by tools.
- The server never prints access or refresh tokens.
- `FITBIT_PRIVACY_MODE` defaults to `structured`. Raw Fitbit JSON is opt-in via `raw` mode or per-call override.
- Structured mode preserves complete upstream physiological records and response metadata while removing GPS and secret-bearing fields.
- Health data is sensitive — do not paste raw payloads publicly.
- This is **not medical advice**. The server exposes user-authorized data for personal AI workflows, not diagnosis or treatment.
## Configuration
`setup` writes most of these into `~/.fitbit-mcp/config.json` (`0600`). Manual env override is supported:
```bash
FITBIT_CLIENT_ID=…
FITBIT_CLIENT_SECRET=…
FITBIT_REDIRECT_URI=http://127.0.0.1:3000/callback
# Optional
FITBIT_SCOPES="activity heartrate profile settings sleep weight nutrition"
FITBIT_PRIVACY_MODE=structured # summary | structured | raw
FITBIT_CACHE=sqlite # optional read-through cache
```
## Hermes / remote setup
```bash
npx -y fitbit-mcp-unofficial setup --client hermes --no-auth
npx -y fitbit-mcp-unofficial auth # run locally if browser auth is needed
npx -y fitbit-mcp-unofficial doctor --client hermes
hermes mcp test fitbit
```
After Hermes config changes, use `/reload-mcp` or `hermes mcp test fitbit`. Don't restart the gateway for normal data access.
If browser OAuth has to happen on a different machine than Hermes, run `auth` locally and copy `~/.fitbit-mcp/tokens.json` to the server with `chmod 600`.
## Requirements
- Node.js 20+
- A Fitbit app at <https://dev.fitbit.com/apps> with redirect URI `http://127.0.0.1:3000/callback`
- Intraday heart-rate access requires the Fitbit app to be approved for intraday data (varies per app)
## Development
```bash
git clone https://github.com/davidmosiah/fitbit-mcp.git
cd fitbit-mcp
npm install
npm test
npm run build
```
Test with MCP Inspector:
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
## Links
- npm: <https://www.npmjs.com/package/fitbit-mcp-unofficial>
- Docs site: <https://wellness.delx.ai/connectors/fitbit>
- Legacy docs: <https://fitbitmcp.vercel.app/>
- GitHub: <https://github.com/davidmosiah/fitbit-mcp>
- Delx Wellness registry: <https://github.com/davidmosiah/delx-wellness>
- Connector quality standard: <https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md>
- Fitbit Web API: <https://dev.fitbit.com/build/reference/web-api/>
<!-- delx-wellness see-also -->
## See also
The full [Delx Wellness](https://wellness.delx.ai) connector library:
| Provider | Package | Repo |
|---|---|---|
| WHOOP | [`whoop-mcp-unofficial`](https://www.npmjs.com/package/whoop-mcp-unofficial) | [whoop-mcp](https://github.com/davidmosiah/whoop-mcp) |
| Oura | [`oura-mcp-unofficial`](https://www.npmjs.com/package/oura-mcp-unofficial) | [ouramcp](https://github.com/davidmosiah/ouramcp) |
| Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garminmcp](https://github.com/davidmosiah/garminmcp) |
| Strava | [`strava-mcp-unofficial`](https://www.npmjs.com/package/strava-mcp-unofficial) | [strava-mcp](https://github.com/davidmosiah/strava-mcp) |
| Fitbit | [`fitbit-mcp-unofficial`](https://www.npmjs.com/package/fitbit-mcp-unofficial) | [fitbit-mcp](https://github.com/davidmosiah/fitbit-mcp) |
| Withings | [`withings-mcp-unofficial`](https://www.npmjs.com/package/withings-mcp-unofficial) | [withingsmcp](https://github.com/davidmosiah/withingsmcp) |
| Apple Health | [`apple-health-mcp-unofficial`](https://www.npmjs.com/package/apple-health-mcp-unofficial) | [apple-health-mcp](https://github.com/davidmosiah/apple-health-mcp) |
| Polar | [`polar-mcp-unofficial`](https://www.npmjs.com/package/polar-mcp-unofficial) | [polarmcp](https://github.com/davidmosiah/polarmcp) |
| Nourish (nutrition) | [`wellness-nourish`](https://www.npmjs.com/package/wellness-nourish) | [wellness-nourish](https://github.com/davidmosiah/wellness-nourish) |
**One-command setup for Hermes** — preconfigures every connector above plus wellness skills + onboarding: [`delx-wellness-hermes`](https://github.com/davidmosiah/delx-wellness-hermes).
<!-- /delx-wellness see-also -->
## 📧 Contact & Support
- 📨 **support@delx.ai** — general questions, integration help, partnerships
- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/fitbit-mcp/issues)
- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X
- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)
## License
MIT — see [LICENSE](LICENSE).
## Disclaimer
This software is provided as-is. It is not a medical device, does not provide medical advice, and should not be used for diagnosis or treatment. Fitbit is migrating to the Google Health API; the integration boundary may change. Always consult qualified professionals for medical concerns.
## Skill or MCP
Same package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP:
```bash
npx -y fitbit-mcp-unofficial call fitbit_connection_status --json '{}'
```
Copy `skill/SKILL.md` into your agent skills dir.