personal-fitbit-mcp-server

Fitbit Web API と連携する MCP (Model Context Protocol) サーバーです。 Claude Desktop や LM Studio などの AI アシスタントから、自然言語で自身の健康データにアクセス・分析できます。

機能

ツール	説明
get_profile	ユーザープロフィールと接続デバイスの情報
get_daily_activity	歩数・カロリー・距離・活動時間のサマリー
get_sleep_log	睡眠時間・ステージ（deep/light/REM/wake）・効率
get_heart_rate	安静時心拍数・心拍ゾーン別時間
get_weight_log	体重・BMI・体脂肪率の推移
get_activity_timeseries	活動量の時系列トレンド
get_health_snapshot	全データを一括取得した健康サマリー

利用例

「今日の睡眠はどうだった？」
「今週の歩数の推移を見せて」
「最近心拍数が高い日はある？」
「先月の体重変化を教えて」
「今日の活動と睡眠をまとめて」

必要なもの

• Python 3.10 以上
• uv パッケージマネージャー
• Fitbit アカウント（Fitbit デバイスを使用中であること）
• Fitbit 開発者アカウント（無料）

セットアップ

1. Fitbit アプリの登録

1. Fitbit 開発者ポータル にアクセスし、Fitbit アカウントでログイン
2. "Register an App" から新規アプリを登録（設定値は下記参照）

項目	設定値
OAuth 2.0 Application Type	Personal
Callback URL	http://localhost:3000/callback
Default Access Type	Read Only
Application Website URL	http://localhost

3. 登録後に表示される Client ID と Client Secret を控えておく

2. インストール

git clone https://github.com/<your-username>/personal-fitbit-mcp-server.git
cd personal-fitbit-mcp-server
uv sync

3. 環境変数の設定

cp .env.example .env

.env を開いて Client ID と Client Secret を記入します。

FITBIT_CLIENT_ID=your_client_id_here
FITBIT_CLIENT_SECRET=your_client_secret_here

⚠️ .env には認証情報が含まれます。.gitignore で除外済みですが、公開リポジトリへのコミットには注意してください。

MCP ホストへの接続設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "fitbit-health": {
      "command": "/path/to/uv",
      "args": [
        "--directory", "/path/to/personal-fitbit-mcp-server",
        "run", "personal-fitbit-mcp-server"
      ],
      "env": {
        "FITBIT_CLIENT_ID": "your_client_id",
        "FITBIT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Note: uv のフルパスは which uv コマンドで確認できます（例: /Users/username/.local/bin/uv）。 Claude Desktop は通常のシェルの PATH を継承しないため、フルパスの指定が必要です。

LM Studio

mcp.json に以下を追加します。

{
  "mcpServers": {
    "fitbit-health": {
      "command": "/path/to/uv",
      "args": [
        "--directory", "/path/to/personal-fitbit-mcp-server",
        "run", "personal-fitbit-mcp-server"
      ],
      "env": {
        "FITBIT_CLIENT_ID": "your_client_id",
        "FITBIT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

初回認証

初めてツールを呼び出すと、OAuth 2.0 認証フローが自動的に開始されます。

1. サーバーの stderr に Fitbit 認証 URL が表示される
2. ブラウザでその URL を開いて Fitbit にログインし、アクセスを許可する
3. http://localhost:3000/callback にリダイレクトされ「Authorization successful!」と表示されたら完了
4. トークンが ~/.fitbit-health-mcp/tokens.json に保存される（以降は自動更新）

開発者向け

MCP Inspector でのテスト

set -a && source .env && set +a
uv run mcp dev src/fitbit_health_mcp/server.py -e .

ブラウザで Inspector UI が開き、各ツールを対話的にテストできます。

ドキュメントについて

docs/design.md はこのプロジェクトの開発前の原案設計書です。 実装過程での仕様変更（アプリ名変更・パラメータ設定等）により、実際のコードと一部異なる箇所があります。 実装の仕様は本 README およびソースコードを参照してください。

プロジェクト構成

src/fitbit_health_mcp/
├── server.py       # FastMCP サーバー定義・ツール登録
├── auth.py         # OAuth 2.0 PKCE 認証フロー
├── client.py       # Fitbit API クライアント
├── formatters.py   # レスポンス整形
├── config.py       # 設定値
└── tools/
    ├── sleep.py
    ├── activity.py
    ├── heart_rate.py
    ├── weight.py
    ├── snapshot.py
    └── profile.py

技術スタック

• FastMCP — MCP サーバー実装
• httpx — 非同期 HTTP クライアント
• OAuth 2.0 Authorization Code Grant with PKCE（自前実装）
• stdio トランスポート（Claude Desktop / LM Studio 両対応）

注意事項

• レート制限: Fitbit API は 150 リクエスト/時間/ユーザーの制限があります。get_health_snapshot は1回の呼び出しで4リクエストを消費します。
• トークンの保存場所: ~/.fitbit-health-mcp/tokens.json（個人利用想定）
• 対応スコープ: activity / heartrate / sleep / weight / profile / settings

AI-Assisted Development

このプロジェクトは Claude (Anthropic) の支援を受けて開発されました。 設計・実装・デバッグのすべてのコードは作者がレビューおよびテスト済みです。

This project was developed with the assistance of Claude (Anthropic). All code has been reviewed and tested by the author.

License

This project is licensed under the MIT License.