Oura Ring

oura-ring-python-mcp

Claude（または任意の MCP クライアント）に、睡眠、コンディション、アクティビティ、ストレス、SpO2、レジリエンス、ワークアウト、セッション、心拍数など、Oura Ring のデータへの読み取り専用アクセスを提供する MCP サーバーです。独自の小規模な非同期クライアント（oura_ring_mcp.core）を使用して、Oura API v2 と通信します。

ツール

ツール	返される内容
get_personal_info	年齢、体重、身長、生物学的性別、メールアドレス
get_daily_sleep	毎日の睡眠スコアと寄与要因
get_sleep_periods	各夜の睡眠と昼寝：睡眠段階、効率、心拍数、HRV
get_daily_readiness	毎日のコンディションスコア、寄与要因、体温の偏差
get_daily_activity	毎日のアクティビティスコア、歩数、カロリー、各アクティビティレベルの時間
get_daily_stress	毎日の高ストレス状態と回復状態の時間
get_daily_spo2	夜間の平均 SpO2 と呼吸障害指数
get_daily_resilience	毎日のレジリエンスレベルと寄与要因
get_workouts	種類、強度、カロリー、距離を含むワークアウト
get_sessions	瞑想、呼吸、休息のセッション
get_heart_rate	最小、最大、平均 bpm を含む心拍数サンプル

日次ツールでは、start_date と end_date を任意で指定できます（YYYY-MM-DD。両端の日付を含みます）。指定しない場合は、今日までの 7 日間が対象となります。期間は最大 90 日間です。各結果には対象期間が含まれるため、モデルは「今日」が何を意味するかを常に把握できます。

get_heart_rate では、start_datetime と end_datetime を任意で指定できます（ISO 8601）。指定しない場合は、過去 24 時間が対象となります。期間は最大 7 日間です。

結果を小さく保つため、区間ごとの系列（5 分ごとのアクティビティ分類、MET、睡眠段階、睡眠中の心拍数と HRV の曲線）は含めず、スコア、合計値、平均値を含めています。

セットアップ

Oura アプリケーションの作成やトラブルシューティングを含む手順ガイドについては、 インストールガイドを参照してください。 ドキュメント全文は https://oura-ring-python-mcp.readthedocs.io にあります。

Oura では個人用アクセストークンが廃止されたため、このサーバーは OAuth2 でサインインします。http://localhost:47651/callbackをリダイレクト URI に含み、email、personal、daily、 heartrate、workout、session、spo2、stressのスコープを許可した Oura API アプリケーション（クライアント ID とシークレット）が必要です（レジリエンスには stressが必要です）。Gen3 および Oura Ring 4 のユーザーが API からデータを取得するには、有効な Oura メンバーシップが必要です。

git clone https://github.com/osjayaprakash/oura-ring-python-mcp.git && cd oura-ring-python-mcp
uv sync

一度サインインします。ブラウザーが開き、localhost への Oura のリダイレクトを受け取り、 トークンを~/.config/oura-ring-mcp/tokens.jsonに保存します（読み取り可能なのは自分だけです）。

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uv run oura-ring-python-mcp auth

以降、サーバーはアクセストークンを自動で更新し（Oura が発行する有効期間は 30 日です）、 新しい使い捨てのリフレッシュトークンを毎回保存します。アクセスを取り消した場合や、保存したリフレッシュトークンを紛失した場合にのみ、再度authを実行してください。

変数	必須	デフォルト	意味
OURA_CLIENT_ID	はい		Oura API アプリケーションのクライアント ID
OURA_CLIENT_SECRET	はい		Oura API アプリケーションのクライアントシークレット
OURA_TOKEN_FILE	いいえ	~/.config/oura-ring-mcp/tokens.json（$XDG_CONFIG_HOMEが設定されている場合はその配下）	authがトークンを保存し、サーバーが読み込む場所
OURA_TIMEZONE	いいえ	マシンのタイムゾーン	IANA タイムゾーン（例：Europe/London）。これにより「今日」が Oura の日付と一致します。デフォルトが UTC となる Docker で実行する場合に設定してください
OURA_REDIRECT_URI	いいえ	http://localhost:47651/callback	アプリケーションのリダイレクト URI と完全に一致する必要があります
OURA_SCOPES	いいえ	email personal daily heartrate workout session spo2 stress	リクエストするスコープ

リダイレクト URI がhttp://localhost:<port>/...ではない場合（または SSH 経由や Docker 内でサインインする場合）、authはブラウザーが最終的に表示した URL を貼り付けるよう求めます。auth --pasteで強制できます。

PyPI から実行する

クローンは不要です。uvが公開済みのパッケージを取得して実行します。

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uvx oura-ring-python-mcp auth   # once
uvx oura-ring-python-mcp

クライアント設定では、"command": "uvx", "args": ["oura-ring-python-mcp"]を使用します。

Docker で実行する

まずホスト上でサインインし（上記参照）、コンテナーがトークンを読み込んで更新済みのトークンを保存できるよう、トークンフォルダーをマウントします。サーバーは stdio 経由で MCP 通信を行うため、-iを付けたままにしてください。

docker run -i --rm --user "$(id -u):$(id -g)" \
  -e OURA_CLIENT_ID -e OURA_CLIENT_SECRET -e OURA_TIMEZONE=Europe/London \
  -v ~/.config/oura-ring-mcp:/tokens \
  ghcr.io/osjayaprakash/oura-ring-python-mcp:latest

イメージは/tokens/tokens.jsonからトークンを読み込みます。Linux では--userを指定すると、コンテナーがトークンファイルを読み込んで更新できます。macOS と Windows の Docker Desktop では不要です。コンテナー内からサインインするには、-itとコマンドauth --pasteを指定して実行します。

クライアント設定では、これらの引数を指定して"command": "docker"を使用し、変数はクライアントのenvブロックで渡します。

Claude Desktop

claude_desktop_config.jsonに追加します。

{
  "mcpServers": {
    "oura": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/oura-ring-python-mcp", "run", "oura-ring-python-mcp"],
      "env": {
        "OURA_CLIENT_ID": "your-client-id",
        "OURA_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

claude mcp add oura \
  -e OURA_CLIENT_ID=your-client-id \
  -e OURA_CLIENT_SECRET=your-client-secret \
  -- uv --directory /absolute/path/to/oura-ring-python-mcp run oura-ring-python-mcp

Langfuse のトレース（任意）

各ツール呼び出しが Langfuse のトレースになり、Oura API 呼び出しごとに子スパンが作成されます。 追加パッケージをインストールし、キーを設定します。

uv sync --extra langfuse

サーバーコマンドでは、run oura-ring-python-mcpの代わりにrun --extra langfuse oura-ring-python-mcpを使用します。

変数	意味
LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY	両方が設定されている場合にのみトレースが有効になります
LANGFUSE_BASE_URL	セルフホストまたはリージョナルインスタンス用の Langfuse URL（デフォルト：Langfuse Cloud）
LANGFUSE_CAPTURE_DATA	ツールの入力、出力、エラーメッセージを含める場合はtrue。デフォルトはfalse

**プライバシー：**睡眠、心拍数、活動データは健康データです。デフォルトでは、トレースに含まれるのはツール名、処理時間、エラーのクラス名のみです。LANGFUSE_CAPTURE_DATA=trueを設定すると、データが Langfuse インスタンスに送信されます。セルフホストのインスタンスなど、信頼できるインスタンスでのみ設定してください。

開発

uv sync
uv run pytest            # offline suite
uv run pytest -m live    # hits the real API; needs `auth` first
uv run ruff check src tests && uv run ruff format --check src tests

リリース

pyproject.toml の version と server.json の両方のバージョンを更新し（テストで一致を確認します）、コミットしてからタグをプッシュします。

git tag v0.1.0 && git push origin v0.1.0

タグをプッシュすると、PyPI（pypi.yml、PYPI_API_TOKEN シークレットが必要）、ghcr.io/osjayaprakash/oura-ring-python-mcp（docker.yml）、そしてMCP Registry（mcp-registry.yml）に公開されます。

ライセンス

MIT