oura-ring-mcp-server

oura-ring-mcp-server

Model Context Protocol に対応した Oura Ring API v2 用サーバーです。Claude（または任意の MCP クライアント）から Oura のデータに接続して、睡眠、コンディション、アクティビティ、心拍数、ワークアウトなどについて質問できます。

somamcp（テレメトリーとイントロスペクション）、 functype（型付きエラーハンドリング）、および zod を使用して構築されています。

設計

エンドポイントごとにツールを用意するのではなく、このサーバーは collection パラメーターを持つ統合された単一の oura_data ツールを公開します。これにより、すべての Oura usercollection エンドポイントをカバーしながら、ツールスキーマを小さく保ち（トークンコストを抑え）ます。選択したコレクションに対して渡されたパラメーターが有効かどうかを検証し、無効な場合は具体的な対処方法を示すメッセージを返します。

要件

• Node.js 24+（.nvmrc で固定）

• Oura のOAuth2 アプリケーション — cloud.ouraring.com/oauth/applications で登録して、クライアント ID とシークレットを取得します。リダイレクト URI を http://localhost:8080/callback に設定し、使用する読み取りスコープを有効にしてください。デフォルトでは全スコープを要求します — email personal daily heartrate tag workout session spo2 ring_configuration stress heart_health — これによりすべてのコレクションが利用できます（特に heart_health は vO2_max と daily_cardiovascular_age の利用に必要です）。

  Oura は 2025 年 12 月に新しい個人アクセストークンの発行を停止したため、新規セットアップでは OAuth2 を使用します。以前に発行された PAT は引き続き利用できます。認証を参照してください。

認証

このサーバーは、自動的に更新される OAuth2 アクセストークンを使って Oura に認証します。組み込みの login コマンドで一度だけ認証します。

# with OURA_CLIENT_ID and OURA_CLIENT_SECRET set in the environment
npx -y oura-ring-mcp-server login

ブラウザーが開いて同意画面が表示され、http://localhost:8080/callback でリダイレクトを受け取り、トークンが ~/.config/oura-ring-mcp/tokens.json に書き込まれます（OURA_TOKEN_STORE で変更できます）。Oura のリフレッシュトークンは一度しか使用できないため、それ以降はサーバーがこのストア内でトークンを管理し、更新します。環境変数にリフレッシュトークンを設定する必要はありません。MCP サーバーは起動時にストアを読み込みます。リフレッシュトークンが取り消された場合にのみ、login を再実行してください。

従来の PAT： 有効な個人アクセストークンをまだお持ちの場合は、代わりに OURA_API_KEY を設定し、OAuth のセットアップを省略できます。両方が設定されている場合は、OAuth が優先されます。

使用方法

Claude Desktop / Claude Code

MCP クライアントの設定に追加します（例：claude_desktop_config.json）。

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "oura-ring-mcp-server"],
      "env": {
        "OURA_CLIENT_ID": "your-oauth-client-id",
        "OURA_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

これにより、ほとんどの MCP クライアントが想定する stdio 経由でサーバーが実行されます。トークンストアを作成するため、先に login を一度実行してください（認証を参照）。

設定

環境変数	必須	デフォルト	説明
OURA_CLIENT_ID	OAuth 用	—	Oura OAuth2 クライアント ID です。
OURA_CLIENT_SECRET	OAuth 用	—	Oura OAuth2 クライアントシークレットです。
OURA_API_KEY	レガシー PAT 用	—	レガシーの個人用アクセストークン（Bearer）です。OAuth の 2 つの値の代わりに使用できます。
OURA_REDIRECT_URI	いいえ	http://localhost:8080/callback	login のリダイレクト URI です。Oura アプリの登録内容と一致する必要があります。
OURA_SCOPES	いいえ	全読み取りスコープ（Requirements を参照）	login 中に要求する、スペース区切りのスコープです。
OURA_TOKEN_STORE	いいえ	~/.config/oura-ring-mcp/tokens.json	OAuth トークンストアのパスです。
OURA_SANDBOX	いいえ	false	実際のデータの代わりに、Oura の /sandbox/ デモデータを使用します。
TRANSPORT_TYPE	いいえ	stdio	stdio または httpStream です。
PORT	いいえ	3000	httpStream トランスポートのポートです。
HOST	いいえ	0.0.0.0	httpStream トランスポートのホストです。
OURA_TELEMETRY_FILE	いいえ	—	NDJSON テレメトリーイベントを書き込むファイルパスです（どのトランスポートでも安全に使用できます）。
OURA_TELEMETRY_CONSOLE	いいえ	true	コンソールテレメトリーです。httpStream のみで有効です（stdio では有効になりません）。

HTTP トランスポート

長時間稼働またはネットワーク経由でのデプロイの場合：

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... TRANSPORT_TYPE=httpStream PORT=3000 npx -y oura-ring-mcp-server

MCP エンドポイントは /mcp で提供されます。somamcp は、公開された GET /health プローブも公開します。

oura_data ツール

パラメーター	対象	備考
collection	すべて	取得するデータコレクションです（以下を参照）。
start_date / end_date	日次コレクション	YYYY-MM-DD 形式です。省略すると直近 7 日間になります。
start_datetime / end_datetime	heartrate、ring_battery_level	ISO-8601 形式です。省略すると直近 24 時間になります。
latest	heartrate、ring_battery_level	最新のサンプルのみを返します。
document_id	詳細ルートのあるコレクション	ID で単一のレコードを取得します。
next_token	リストコレクション	前回のレスポンスから取得したページネーションカーソルです。
fields	リストコレクション	カンマ区切りのフィールドセットです。

コレクション

日次（start_date/end_date）：daily_activity、daily_sleep、daily_readiness、 daily_spo2、daily_stress、daily_resilience、daily_cardiovascular_age、vO2_max、 sleep、sleep_time、session、workout、tag、enhanced_tag、rest_mode_period

時系列（start_datetime/end_datetime）：heartrate、ring_battery_level

リスト／シングルトン：ring_configuration、personal_info

プロンプトの例

• 「先週の平均レディネススコアはいくつでしたか？」
• 「2026-06-20の夜の睡眠ステージを表示してください。」
• 「最新の心拍数の測定値を取得してください。」
• 「今月は何回ワークアウトを記録しましたか？また、それぞれの時間はどのくらいでしたか？」

開発

pnpm install
pnpm validate   # format + lint + typecheck + test + build
pnpm dev        # watch build
pnpm inspect    # run against the MCP Inspector

リングがなくても試せるように、OURA_SANDBOX=trueを設定してOuraのデモデータセットに接続してください。

ライセンス

MIT