fitbit-mcp

fitbit-mcp

提供終了しました。代わりに google-health-mcp をご利用ください。

Fitbit Web API は 2026年9月30日 に終了します。また、Fitbit は新しいアプリの登録受付を停止しているため、このパッケージを新規にセットアップすることはできません。以下の 手順 2 では登録済みの個人用アプリが必要ですが、新たに作成する方法はもうありません。既存のインストールは終了日まで動作します。

google-health-mcp は Google Health API を通じて同じ測定データを扱い、さらに ECG と不整脈通知にも対応しています。履歴はこのパッケージのキャッシュではなく Google から読み込むため、移行作業は不要です。インストールして、バックフィルを 1 回実行してください。

すべてのデータを引き継げるわけではありません。Fitbit のアクティビティ目標とサーバー側の累計記録には相当する機能がありません。また、Google が提供していない項目には、心拍ゾーン、アクティブ分の内訳、単一の数値ではなく範囲としての VO2 max、睡眠効率、SpO2 の最高値と最低値、BMI があります。9月30日以降はこのパッケージでもこれらを取得できなくなるため、保持したい場合はそれまでに fitbit.db をコピーしてください。

OAuth PKCE、ローカル SQLite キャッシュ、トレンド分析に対応した Fitbit Web API 用 MCP サーバーです。

Claude Code やその他の MCP クライアント向けに設計されています。Fitbit のデータをローカルデータベースに同期するため、高速かつオフラインでクエリできます。初回同期後に API 呼び出しは不要です。

特長

• OAuth 2.0 PKCE - クライアントシークレット不要の安全な認証フロー
• ローカル SQLite キャッシュ - 1 回同期するだけで、すぐにクエリできます
• 差分同期 - 前回の同期以降に追加されたデータのみを取得します
• MCP ツール - 同期、クエリ（キャッシュ対象のデータ型と、ライブ取得のみのデバイス／累計記録／目標）、トレンド分析
• ライブモード - キャッシュを迂回して API に直接クエリします
• CLI - コマンドラインから認証を設定し、同期や JSON のインポートを実行できます
• レート制限への対応 - アクティビティと食事ログの同期では 429 の際に待機して再試行します。それ以外のデータ型では rate_limited を報告し、次回の同期で再開します

データ型

ツール	データ
fitbit_get_heart_rate	安静時心拍数、心拍ゾーン
fitbit_get_activity	歩数、カロリー、アクティブ分、距離
fitbit_get_exercises	運動セッション（名前、時間、心拍数、カロリー）
fitbit_get_sleep	睡眠時間、効率、睡眠ステージ
fitbit_get_weight	体重、BMI、体脂肪率
fitbit_get_spo2	血中酸素飽和度（平均／最小／最大）
fitbit_get_hrv	心拍変動（RMSSD）
fitbit_get_azm	ゾーン別内訳付きのアクティブゾーン分数
fitbit_get_breathing_rate	夜間の 1 分あたりの呼吸数
fitbit_get_skin_temperature	夜間の皮膚温の変化（基準値からの摂氏温度）
fitbit_get_core_temperature	手動で記録した深部（体内）体温の測定値（摂氏温度）
fitbit_get_cardio_fitness	VO2 Max／カーディオフィットネススコア
fitbit_get_food_log	1 日の食事カロリーと水分摂取量
fitbit_get_devices	ペアリング済みデバイス、バッテリー残量、最終同期（ライブ）
fitbit_get_lifetime_stats	累計記録と自己ベスト記録（ライブ）
fitbit_get_goals	ユーザーが設定した日／週ごとのアクティビティ目標（ライブ）
fitbit_trends	集計平均（週／月／四半期）

要件

• Python 3.13 以降（CI では 3.13 および 3.14 でテスト済み）
• 個人用アプリを登録済みの Fitbit 開発者アカウント

セットアップ

1. インストール

pip install fitbit-mcp

または、インストールせずに実行します。

uvx fitbit-mcp

クローンから開発する場合：

pip install -e ".[dev]"

2. Fitbit アプリを登録する

1. dev.fitbit.com/apps にアクセスして、新しいアプリを作成します
2. OAuth 2.0 Application Type を Personal に設定します
3. Redirect URL を http://localhost:8080 に設定します
4. Client ID を控えます（クライアントシークレットは不要です。PKCE では使用しません）

3. 認証する

fitbit-mcp auth

Fitbit へのログインのためにブラウザーが開き、PKCE を介して認証コードを交換し、トークンがローカルに保存されます。

トークンは ~/.config/fitbit-mcp/fitbit_tokens.json にアクセス許可 0600 で保存されます。アクセストークンの有効期限は 8 時間で、自動的に更新されます。リフレッシュトークンは 90 日間操作がないと有効期限が切れます。

4. Claude Code に登録する

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

5. 初回同期（任意）

クエリツールは初回使用時に自動同期されるため、この手順は省略できます。キャッシュに事前データを読み込む場合や、より長期間の履歴を同期する場合は、次を実行します。

fitbit-mcp sync --days 30

CLI の使用方法

fitbit-mcp              Start the MCP server (stdio transport)
fitbit-mcp -V, --version  Print the installed package version
fitbit-mcp auth         Interactive OAuth setup
fitbit-mcp doctor       Check the setup and report what needs fixing
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)
  --since YYYY-MM-DD    Backfill from this date, overriding the incremental
                        resume-from-last-sync cursor and --days
  --until YYYY-MM-DD    Inclusive end date for a --since backfill; together
                        they re-fetch exactly that window (e.g. to repair a
                        gap in the middle of the cache)
fitbit-mcp import       Import existing JSON data files
  --data-dir PATH       Directory containing JSON files

MCP ツールのリファレンス

クエリツールは、データタイプごとに毎日の初回クエリ時に自動同期されます。キャッシュを完全にバイパスして API から直接取得するには、live=True を使用します。

すべてのクエリツールで、次の共通パラメーターを使用できます。

• start_date - 開始日。YYYY-MM-DD、YYYY-MM、または 30d（相対指定）で指定します。デフォルト：過去 30 日間。
• end_date - 終了日。YYYY-MM-DD で指定します。デフォルト：今日。
• live - true の場合、キャッシュではなく Fitbit API から取得します（自動同期をバイパスします）。

fitbit_get_exercises では、次のパラメーターも使用できます。

• exercise_type - アクティビティ名でフィルターします（大文字と小文字を区別しない部分一致）。例："cycling"、"walk"、"run"。デフォルト：すべてのタイプ。

fitbit_sync

Fitbit API からローカルの SQLite キャッシュにデータを同期します。クエリツールは毎日の初回使用時に自動で同期するため、明示的な呼び出しが必要なのは、より長期間の履歴を取得する場合や、強制的に更新する場合のみです。

• data_types - 同期するデータ：all、heart_rate、activity、exercises、sleep、weight、spo2、hrv、azm、breathing_rate、skin_temperature、core_temperature、cardio_fitness、food_log。カンマ区切りで指定します。デフォルト：all。
• days - 初回同期で取得する履歴の日数（デフォルト：30）。2 回目以降の同期は差分同期です。
• since - 任意の YYYY-MM-DD。この日付から、キャッシュ済みデータにかかわらずバックフィルし、差分再開と days の指定を上書きします。
• until - 任意の YYYY-MM-DD の終了日（その日を含む）。since が必要です。両方を指定すると、since〜until の期間のみを再取得してアップサートします。今日までのデータをすべて再取得せずに、キャッシュの途中にある欠落期間を修復する場合に使用します。

fitbit_trends

キャッシュ済みデータを集計して傾向を分析します。

• data_type - 分析するデータ：heart_rate、activity、exercises、sleep、weight、spo2、hrv、azm、breathing_rate、skin_temperature、core_temperature、cardio_fitness、food_log。デフォルト：activity。
• period - 集計期間：weekly、monthly、quarterly。デフォルト：monthly。
• start_date - 開始日。デフォルト：過去 12 か月（365 日）。
• end_date - 終了日。デフォルト：今日。
• compare - 2 つの期間を比較します：last_30d vs previous_30d、2026-03 vs 2026-02、2026-Q1 vs 2025-Q4。指定した場合、period／start_date／end_date は無視されます。

OAuth スコープ

セットアップ時に、次の Fitbit API スコープがリクエストされます。

スコープ	アクセスするデータ
activity	歩数、消費カロリー、アクティブ時間、距離、AZM、生涯統計、目標
heartrate	安静時心拍数、心拍ゾーン、HRV
sleep	睡眠時間と睡眠ステージ
weight	体重、BMI、体脂肪率
oxygen_saturation	SpO2（血中酸素）
profile	ユーザープロフィール（ユーザー ID、表示名）
respiratory_rate	夜間の呼吸数
temperature	皮膚温の変動と手動で記録した深部体温
cardio_fitness	VO2 Max ／カーディオフィットネススコア
nutrition	毎日の食事のカロリーと水分の記録
location	記録したエクササイズの GPS データ
settings	ペアリング済みデバイス（バッテリー、最終同期）

これらはすべてのツールで必要なスコープです。一部だけが必要な場合は、セットアップ前に config.py の FITBIT_SCOPES を編集してください。より少ないスコープセットからアップグレードした後は、fitbit-mcp auth を再実行して再認証してください。

設定

環境変数を使ってパスを変更できます。

変数	デフォルト	説明
FITBIT_MCP_CONFIG_DIR	~/.config/fitbit-mcp/	OAuth 認証情報のディレクトリ
FITBIT_MCP_DB_PATH	~/.local/share/fitbit-mcp/fitbit.db	SQLite データベースのパス
FITBIT_MCP_OFFLINE	未設定	真の場合（1、true、yes、on）、キャッシュのみを読み取ります。認証情報は不要です。以下を参照してください。

オフライン／キャッシュのみのモード

デフォルトでは、サーバーは要求に応じて自動同期するため、クエリツールは cron ジョブなしで最新のデータを取得します。純粋なキャッシュリーダーとして実行するには、FITBIT_MCP_OFFLINE=1 を設定します。

• Fitbit の認証情報は不要です。サーバーがトークンファイルにアクセスすることはありません。
• ライブ API 呼び出しは行われません。自動同期は無効になり、live=True、ライブ専用ツール（fitbit_get_devices、fitbit_get_lifetime_stats、fitbit_get_goals）、および fitbit_sync は API を呼び出す代わりに、「オフラインモード」であることを示す明確なメッセージを返します。
• クエリツールはローカルの SQLite キャッシュにあるデータを返します。応答には "offline_mode": true のタグが付きます。

一般的な用途：

• マルチデバイス構成 — 1 台のホストで共有データベースに対して fitbit-mcp sync を実行し（cron／systemd 経由）、ほかのホストでは FITBIT_MCP_OFFLINE=1 を設定して FITBIT_MCP_DB_PATH を同じキャッシュに指定し、読み取りのみを行います。これにより、Fitbit OAuth トークン（1 回限りでローテーションするもの）を厳密に 1 台のホストだけが所有し、更新時の競合を回避できます。
• CI とプライバシー — ネットワークアクセスも認証情報もなしでクエリを実行できます。

この場合、キャッシュを最新に保つのは同期ホストの役割です。オンデマンドの自動同期に戻すには、FITBIT_MCP_OFFLINE の設定を解除してください。

レート制限

Fitbit API では、1 時間あたり 150 件のリクエストが許可されています。アクティビティと食事の記録の同期は、429 が返された場合にスリープして自動的に再試行します。一方、日付範囲を指定するデータタイプでは、その同期を rate_limited として記録し、次回の実行時に再開します。次の点にご注意ください。

• アクティビティと食事の記録の同期では、1 日あたり API 呼び出しを 1 回使用します（日付範囲エンドポイントはありません）。
• どちらも初回同期で 30 日分を取得すると、150 件／時間の上限のうち約 30 件を使用します。
• 心拍数、睡眠、体重、SpO2、HRV、AZM、呼吸数、皮膚温、深部体温、カーディオフィットネスでは日付範囲エンドポイントを使用するため、はるかに効率的です。

キャッシュからクエリして API 呼び出しを完全に避けるには、live=False（デフォルト）を使用してください。

データの安全性

このプロジェクトには、次のファイルを誤ってコミットするのを防ぐ pre-commit フック（scripts/check-no-data.sh）が含まれています。

• データベースファイル（*.db、*.db-journal、*.db-wal）
• 設定／認証情報（config/*.json）
• 大きなファイル（>100KB）

クローン後にインストールしてください。

ln -sf ../../scripts/check-no-data.sh .git/hooks/pre-commit

既存データのインポート

既存の Fitbit データが JSON ファイル（以前のエクスポートやスクリプトによるものなど）としてある場合は、一括インポートできます。

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

想定されるファイル名：heart_rate.json、activity.json、exercises.json、sleep.json、weight.json、spo2.json、hrv.json。想定される JSON 形式については、src/fitbit_mcp/importer.py を参照してください。現在、インポートできるのはこれら7種類のみです。新しい種類（AZM、呼吸数、皮膚温度／深部体温、心肺機能、食事記録）はインポートではなく、sync で取り込まれます。

貢献

開発環境のセットアップ、テストのワークフロー、コミット前フックについては、CONTRIBUTING.md を参照してください。変更履歴は CHANGELOG.md で確認できます。

ライセンス

GPL-3.0-or-later