# 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](https://docs.astral.sh/uv/) パッケージマネージャー
- Fitbit アカウント（Fitbit デバイスを使用中であること）
- Fitbit 開発者アカウント（無料）

## セットアップ

### 1. Fitbit アプリの登録

1. [Fitbit 開発者ポータル](https://dev.fitbit.com) にアクセスし、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. インストール

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

### 3. 環境変数の設定

```bash
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` を編集します。

```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` に以下を追加します。

```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 でのテスト

```bash
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](https://github.com/jlowin/fastmcp) — MCP サーバー実装
- [httpx](https://www.python-httpx.org/) — 非同期 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](https://claude.ai) (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](LICENSE).