Polar Health Data (self-hosted)

polar-flow-server

Polar デバイス向けのセルフホスト可能な健康分析ツールです。データを自分で管理し、自分自身のベースラインと照らし合わせて分析し、AI アシスタントにデータを読み取らせることができます。

ドキュメント全文 · MCP サーバー · 連携ガイド · API リファレンス

このツールでできること

あなたの時計は、あなた自身よりもあなたのことをよく知っています。しかし、Polar の API では直近 28～30 日分のデータしか確認できません。このサーバーはすべてのデータを同期して永久に保存し、さまざまな質問への回答に役立てます。

1. Polar API の 13 個すべてのエンドポイントを自動的に同期します。睡眠、HRV、アクティビティ、ワークアウト、SpO2、ECG、皮膚温などに対応しています
2. すべてのデータを PostgreSQL に保存します。データもサーバーも自分で管理でき、間にクラウドを挟みません
3. 個人ベースライン（移動平均、IQR による異常値の範囲）を算出するため、「これは正常か？」を「あなたにとって正常か？」という意味で判断できます
4. OAuth サインイン機能を備えた組み込み MCP サーバーを搭載しています。Claude に「今日はハードなトレーニングをするべき？」と尋ねると、夜間の HRV をベースラインと比較して回答します
5. 管理ダッシュボード（HTMX）、REST API、ユーザーごとの API キーを備え、複数ユーザーに対応しています

AI に自分の体について尋ねる（MCP）

組み込みの Model Context Protocol サーバーは、プロトコルリビジョン 2026-07-28 のストリーミング可能な HTTP 形式で、メインサーバー内の /mcp で動作します。10 個の厳選されたツールで、1 回の健康評価、睡眠、回復、アクティビティ、ワークアウト、7 種類のバイオセンシングデータ、個人ベースライン、パターンや異常、同期の制御に対応します。

MCP Apps を表示できるクライアント（claude.ai、Claude Desktop、VS Code）では、「調子はどう？」と尋ねると、会話内に実際のカードが表示されます。

接続はサインインであり、トークンの貼り付けではありません。 BASE_URL を設定すると、このサーバー自体が OAuth 2.1 認可サーバーになります。Claude Desktop または claude.ai で https://your-server/mcp をカスタムコネクターとして追加し、接続をクリックして、自分のサーバーにログインし、同意画面で承認します。トークンはユーザーごとに管理され、有効期限は 1 時間です。自動的に更新され、接続したアプリはすべて設定からいつでも取り消せます。ヘッドレスクライアントでは、引き続き API キーを使用できます。

claude mcp add polar-health https://your-server.example.com/mcp \
  --transport http \
  --header "X-API-Key: pfk_your_key_here"

詳しいセットアップ方法は、MCP ドキュメントをご覧ください。

アーキテクチャ

Polar API → polar-flow SDK → Sync Service → PostgreSQL
                                                  ↓
                                           Admin Dashboard (HTMX)
                                                  ↓
                                             REST API

技術スタック：

• Litestar（非同期 Web フレームワーク）
• SQLAlchemy 2.0（非同期 ORM）
• PostgreSQL
• HTMX + Tailwind（管理 UI）
• polar-flow SDK v1.5.0

サーバーを運用するのはちょっと……という方へ。 ホステッド版を準備中です。ウェイティングリストに登録してください。セルフホスト版は今後もずっと無料です。

クイックスタート

オプション 1：Docker（推奨）

# Pull and run
curl -O https://raw.githubusercontent.com/StuMason/polar-flow-server/main/docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml up -d

# That's it. Open http://localhost:8000/admin

オプション 2：ソースから実行

git clone https://github.com/StuMason/polar-flow-server.git
cd polar-flow-server
docker-compose up -d

セットアップ

1. http://localhost:8000/admin を開きます
2. admin.polaraccesslink.com から Polar の認証情報を取得します（リダイレクト URI を http://localhost:8000/admin/oauth/callback に設定します）
3. 認証情報を入力して、「Polar に接続」をクリックします
4. 「今すぐ同期」をクリックして、データを取得します

サーバーは 1 時間ごとにデータを自動同期します。

ダッシュボード

/admin/dashboard の管理パネルはタブで構成されています（モバイルではタブバーがフローティング表示されます）。

• 概要 - 統計タイル（HRV、安静時心拍数、SpO2、皮膚温、歩数、負荷、睡眠スコア、覚醒度など）、今日のコンディションに関するおすすめ、「今日の概要」ミニチャート（睡眠ステージ、心拍数、歩数）
• トレンドとベースライン - 個人のベースラインと検出されたパターン
• 睡眠 - 睡眠スコアとステージ別時間のチャート
• 心拍数 - 1日のHR、HRV、ANSチャージのチャート、生体センシングパネル
• トレーニング負荷 - アクティビティとカーディオ負荷のチャート

チャートでは7／14／30日間の範囲を選択でき、CSVにエクスポートできます。APIキーは設定ページで管理でき、レート制限の状況も追跡できます。フロントエンドのアセットはすべて同梱されているため、ダッシュボードはオフラインでも、CDNのないLAN環境でも動作します。

同期されるデータ（13個のエンドポイント）

エンドポイント	データ
睡眠	スコア、ステージ（浅い／深い／REM）、時間
Nightly Recharge	HRV、ANSチャージ、回復状況
Daily Activity	歩数、距離、カロリー、活動時間
Exercises	スポーツ、時間、心拍ゾーン、トレーニング負荷
Cardio Load	負荷、許容量、負荷比、状態
SleepWise Alertness	時間ごとの覚醒度予測
SleepWise Bedtime	最適な睡眠タイミングのおすすめ
Activity Samples	分単位の歩数データ
Continuous HR	1日を通した心拍数（5分間隔）
SpO2	血中酸素の測定値（対応デバイス）
ECG	心電図の測定値（対応デバイス）
Body Temperature	継続的な体温
Skin Temperature	ベースラインからの偏差を含む夜間の皮膚温

設定

必須の環境変数

変数	説明	必須
DATABASE_URL	PostgreSQL接続文字列	はい
ENCRYPTION_KEY	トークン暗号化用の32バイトのFernetキー	はい（本番環境）

暗号化キーを生成します：

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

任意の環境変数

変数	説明	デフォルト
DEPLOYMENT_MODE	self_hosted または saas	self_hosted
SYNC_INTERVAL_HOURS	自動同期の間隔	1
SYNC_ON_STARTUP	サーバー起動時に同期するかどうか	false
SYNC_DAYS_LOOKBACK	同期する過去の日数	28
LOG_LEVEL	ログの詳細度	INFO
API_KEY	マスターAPIキー（レート制限を回避）	なし

API認証

APIエンドポイントには認証が必要です。 健康データを一般公開してはなりません。

認証方法

1. ユーザーごとのAPIキー（推奨）- 管理ダッシュボードまたはOAuthフローから作成します
2. マスターAPIキー - API_KEY 環境変数を設定すると、すべてのアクセスが可能になります（レート制限を回避）

APIキーの使用

# With per-user API key (includes rate limit headers)
curl -H "X-API-Key: pfk_your_api_key_here" \
  http://localhost:8000/api/v1/users/{user_id}/sleep?days=7

# Response headers include:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 999
# X-RateLimit-Reset: 1704067200

レート制限

• デフォルト：APIキーごとに1時間あたり1000リクエスト
• レート制限は1時間ごとにリセットされます
• マスターAPIキー（API_KEY 環境変数）はレート制限を回避します
• レート制限情報はレスポンスヘッダーに返されます

OAuth連携（SaaS／マルチユーザー）

polar-flow-serverとの連携が必要なアプリケーション向けです（例：Laravel、モバイルアプリ、ウェブフロントエンド）。

これにより、すべてのPolarユーザーが自分のアカウントをアプリケーションに接続できるようになります。

OAuthフロー

┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│  Your App       │────▶│  polar-flow-server  │────▶│  Polar Flow     │
│  (Laravel etc)  │     │                     │     │  (OAuth)        │
│                 │◀────│                     │◀────│                 │
└─────────────────┘     └─────────────────────┘     └─────────────────┘

ステップ1：OAuthを開始するためにユーザーをリダイレクトする

GET /oauth/start?callback_url=https://yourapp.com/callback&client_id=your-app-name

パラメーター	必須	説明
callback_url	はい	OAuth後のリダイレクト先（アプリのコールバックエンドポイント）
client_id	いいえ	アプリの識別子（交換時に検証されます）

ステップ2：ユーザーがPolarで認証する

ユーザーはPolarにリダイレクトされ、認証情報でログインして、アプリを承認します。

ステップ3：ユーザーがコールバック先にリダイレクトされる

https://yourapp.com/callback?code=TEMP_CODE_HERE

ステップ4：一時コードをAPIキーと交換する（サーバー間通信）

POST /oauth/exchange
Content-Type: application/json

{
  "code": "TEMP_CODE_HERE",
  "client_id": "your-app-name"
}

レスポンス：

{
  "api_key": "pfk_abc123...",
  "polar_user_id": "12345678",
  "expires_at": null
}

ステップ5：APIキーを保存して使用する

このユーザーの api_key と polar_user_id を保存します。すべてのデータリクエストでAPIキーを使用します：

curl -H "X-API-Key: pfk_abc123..." \
  "https://your-polar-server.com/api/v1/users/12345678/sleep?days=7"

Polar 管理画面の設定

admin.polaraccesslink.comで、アプリのリダイレクト URI を次のように設定します。

https://your-polar-server.com/oauth/callback

キー管理

# Get key info
GET /api/v1/users/{user_id}/api-key/info
X-API-Key: pfk_...

# Regenerate key (invalidates old key)
POST /api/v1/users/{user_id}/api-key/regenerate
X-API-Key: pfk_...

# Revoke key
POST /api/v1/users/{user_id}/api-key/revoke
X-API-Key: pfk_...

API エンドポイント

# Health check (no auth required)
curl http://localhost:8000/health

# Get sleep data (last 7 days)
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/sleep?days=7"

# Get activity data
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/activity?days=7"

# Get nightly recharge (HRV)
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/recharge?days=7"

# Get exercises
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/exercises?days=30"

# Export summary
curl -H "X-API-Key: pfk_..." \
  "http://localhost:8000/api/v1/users/{user_id}/export/summary?days=30"

開発

# Install dependencies
uv sync --all-extras

# Start PostgreSQL
docker-compose up -d postgres

# Run server with hot reload
uv run uvicorn polar_flow_server.app:app --reload

# Run tests
uv run pytest

# Type check
uv run mypy src/polar_flow_server

# Lint
uv run ruff check src/

本番環境へのデプロイ

Docker を実行できる場所であれば、どこにでもデプロイできます。

# Download and run
curl -O https://raw.githubusercontent.com/StuMason/polar-flow-server/main/docker-compose.prod.yml
docker-compose -f docker-compose.prod.yml up -d

Coolify、Railway、Render など - GitHub リポジトリを指定すると、Dockerfile からビルドされます。

本番環境で必要な設定：

• ENCRYPTION_KEY 環境変数を設定します（設定しないと、トークンは再起動後に保持されません）
• DATABASE_URL に PostgreSQL インスタンスを設定します

データベースのマイグレーションは起動時に自動で実行されます。

マルチテナント

このサーバーは、標準で複数ユーザーに対応しています。

• すべてのテーブルに user_id カラムがあります
• すべてのクエリは user_id でスコープされます
• ユーザーごとの API キーにより、各ユーザーは自分のデータにのみアクセスできます
• セルフホストの場合：通常は 1 人のユーザーです
• マルチユーザーの場合：同じコードベースを多くのユーザーで利用します

使用技術

• polar-flow - Polar AccessLink API 用 Python SDK
• Litestar - 非同期 Web フレームワーク
• SQLAlchemy - 非同期 ORM
• HTMX - 管理画面の操作
• Tailwind CSS - スタイリング

ライセンス

MIT