withings-mcp

withings-mcp

OAuth、ローカルの SQLite キャッシュ、傾向分析に対応した、Withings Health API 用の MCP サーバーです。

ほかの Withings MCP サーバーとの違い：

• 高速なオフラインクエリと過去の傾向分析に対応するローカルの SQLite キャッシュ
• 増分同期により、前回の同期以降の新しいデータのみを取得
• 幅広い Withings データに対応：17 種類の体組成指標に加え、睡眠、毎日の活動、ワークアウト、ECG／AFib
• OAuth トークンを自動更新（アクセストークン：3 時間、リフレッシュトークン：1 年）
• mcp 以外の依存関係は不要（HTTP 通信には標準ライブラリを使用）
• Python 3.13 以降（CI で Linux、macOS、Windows 上の 3.13 および 3.14 をテスト済み）

ツール

ツール	説明	データソース
withings_sync	Withings API のデータをローカルキャッシュに同期	ライブ API -> SQLite
withings_get_body	体組成（体重、体脂肪率、筋肉量、骨量、血圧、SpO2）	ローカルキャッシュ（古い場合は自動同期）
withings_get_sleep	睡眠の概要、または detail=True による詳細な睡眠段階の時系列データ	キャッシュ（概要）／ライブ（詳細）
withings_get_activity	1 日の歩数、距離、カロリー、活動時間	ローカルキャッシュ（古い場合は自動同期）
withings_get_workouts	種類、時間、心拍数を含むワークアウトセッション	ローカルキャッシュ（古い場合は自動同期）
withings_get_heart	ECG 記録と AFib 検出	ライブ API（常時）
withings_get_devices	バッテリー状態を含む接続済みデバイス	ライブ API（常時）
withings_trends	期間ごとの平均、週次／月次／四半期ごとの傾向、比較	ローカルキャッシュ（古い場合は自動同期）

キャッシュを利用するクエリツールは、データが古い場合に自動で同期します。また、live=True を指定するとキャッシュを迂回し、Withings API から直接データを取得します。withings_get_heart と withings_get_devices は常にライブでデータを取得します。withings_get_sleep(detail=True) は、分単位の睡眠段階を返します（ライブ取得。1 回のリクエストにつき最大 7 日分）。

前提条件

• Python 3.13 以降（CI で Linux、macOS、Windows 上の 3.13 および 3.14 をテスト済み）
• uv（推奨）または pip
• Withings の開発者アカウントと登録済みアプリケーション

インストール

pip install withings-mcp

インストールせずに uvx withings-mcp で実行することもできます。クローンから開発する場合：

git clone https://github.com/partymola/withings-mcp.git
cd withings-mcp
uv venv --python 3.13 .venv
uv pip install -e .

セットアップ

1. Withings アプリを登録する

1. https://developer.withings.com/dashboard にアクセスします
2. 新しいアプリケーションを作成します
3. コールバック URL を http://localhost:8585 に設定します
4. Client ID と Client Secret を控えます

2. 認証する

.venv/bin/withings-mcp auth

Withings の認証画面を開くため、ブラウザーが起動します。承認すると、トークンはローカルの config/ に保存されます。

3. Claude Code に登録する

claude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcp

4. 初回同期

Claude Code で「Withings のデータを同期して」と入力します。

これにより withings_sync が実行され、ローカルキャッシュにデータが保存されます。次回以降の同期では、新しいデータのみが取得されます。

期待したデータが見つからない、同期が行われなくなったなど、動作しない場合は withings-mcp doctor を実行してください。実際に使用されているパスと認証情報、および修正が必要な項目が報告されます。API 呼び出しは行われません。

MCP クライアントを使わず、コマンドラインから同期することもできます：

.venv/bin/withings-mcp sync                      # all data types, last 30 days
.venv/bin/withings-mcp sync --types body,sleep   # a subset
.venv/bin/withings-mcp sync --days 90            # deeper history on first sync

CLI

withings-mcp              Start the MCP server (stdio transport)
withings-mcp auth         Interactive OAuth setup (opens the browser)
withings-mcp sync         Sync data to the local cache (--types, --days)
withings-mcp doctor       Check the setup and report what needs fixing
withings-mcp --version    Print the installed package version

設定

環境変数	デフォルト	説明
WITHINGS_MCP_CONFIG_DIR	./config/	認証情報とトークンを保存するディレクトリ
WITHINGS_MCP_DB_PATH	./withings.db	SQLite データベースのパス

プロンプトの例

• 「Withings のデータを同期して」
• 「過去3か月の体重を表示して」
• 「今年、睡眠はどのように変化しましたか？」
• 「今月と先月の体組成を比較して」
• 「3月に行ったワークアウトは何ですか？」
• 「接続している Withings デバイスを教えて」
• 「四半期ごとの睡眠傾向を表示して」

開発

# Install with dev dependencies
uv pip install -e . && uv pip install pytest

# Run tests (all use in-memory SQLite with fictional data)
.venv/bin/python -m pytest tests/ -v      # .venv\Scripts\python on Windows

セキュリティ

• 読み取り専用：Withings サーバー上のデータを変更するツールはありません
• ローカルストレージ：健康データはローカルの SQLite データベースに保存されます
• トークンの保存：OAuth トークンは config/ に保存されます（Git の追跡対象外。POSIX では 0600 で作成されます。Windows ではモードは無視され、アクセスは ACL によって管理されます）
• エラーメッセージ：健康データの値は含まず、ステータスコードのみを含みます
• コミット前フック：オプションのフック（scripts/check-no-data.sh）は、データベースファイル、config/ 内のファイル、大きなファイルがコミットされるのを防ぎます。ファイルの内容は読み取りません。CONTRIBUTING.md に記載されているワンライナーでインストールできます

貢献

開発環境のセットアップ、テストのワークフロー、コミット前フックについては、CONTRIBUTING.md をご覧ください。変更内容は CHANGELOG.md で管理されています。

ライセンス

GPL-3.0-or-later