Oura Ring

oura-mcp

Oura Ring API v2 用の Model Context Protocol サーバーです。OAuth を介して、睡眠、アクティビティ、コンディション、心拍数、ワークアウトのデータを MCP 対応クライアント（Claude Desktop、Claude Code、Cursor など）に提供します。

クイックスタート

npx @yasuakiomokawa/oura-mcp configure

ウィザードでは、Oura のクライアント ID／シークレットを入力し、ブラウザーでの OAuth 認証を行います。トークンは ~/.config/oura-mcp/ に保存され、検出された MCP クライアント設定には mcpServers.oura エントリーが追加されます。クライアントを再起動すると、以下のツールを利用できます。

configure を再実行すると、保存済みのクライアント ID とポートがあらかじめ入力されるため、変更しない場合は Enter キーを押すだけです。保存状態を消去して最初からやり直すには、--force と入力します。

npx @yasuakiomokawa/oura-mcp configure --force

前提条件

1. https://cloud.ouraring.com/oauth/applications で Oura 開発者アプリを登録します
2. リダイレクト URI は正確に次の値にする必要があります：http://localhost:54321/callback （OURA_CALLBACK_PORT を変更する場合は http://localhost:<port>/callback）
3. 必要な読み取りスコープを有効にします（Email、Personal info、Daily activity、Heart rate、Workout、Tag、Session、SpO2、Ring configuration、Stress、Heart health）
4. クライアント ID とクライアントシークレットを控えておきます。npx @yasuakiomokawa/oura-mcp configure の実行時に入力します

インストール

クライアントに応じて、次の 3 つの方法があります。

1. MCP レジストリ（自動検出対応クライアント）

公式 MCP レジストリへの公開後、対応クライアントの UI から io.github.YasuakiOmokawa/oura-mcp をインストールできます。OAuth トークンを取得するには、ウィザードの手順を一度実行する必要があります。

2. 手動設定（Claude Desktop／Claude Code／Cursor）

npx @yasuakiomokawa/oura-mcp configure を実行します。ウィザードのステップ 4 で、次の場所が自動検出されます。

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Claude Code（ユーザー）：~/.claude.json
• Claude Code（プロジェクト）：./.mcp.json
• Cursor（ユーザー）：~/.cursor/mcp.json
• Cursor（プロジェクト）：./.cursor/mcp.json

検出されたファイルは、アトミック書き込みの前に <file>.bak.<ISO-timestamp> としてバックアップされます。

手動で設定するには、クライアント設定に次の内容を追加します。

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@yasuakiomokawa/oura-mcp"]
    }
  }
}

3. スキル（任意）

付属の oura-api-skill には、エンドポイントごとのリファレンスと 3 つのワークフローのレシピ（週次レビュー／睡眠傾向／回復状況の確認）が含まれています。Claude Code プラグインとしてパッケージ化するか、スキルディレクトリにインポートできます。

提供するツール

ツール	目的
oura_authenticate	ブラウザーで OAuth フローを開始し、URL を返します。refresh_token の有効期限が切れた後に使用します。
oura_auth_status	現在のトークンの有効性と有効期限を確認します。
oura_clear_auth	保存済みのトークンを消去します。
oura_api_list_paths	対応するすべての GET エンドポイントを概要付きで一覧表示します。
oura_api_get	/v2/... への汎用 GET です。max_pages（1～20）で自動ページネーションを行うか、params に next_token を指定できます。

oura_api_get は { status, data, next_token, pages_fetched, has_more } を含む structuredContent を返します。

設定

方法は 2 つあります。設定ファイル（オプション A）の使用を推奨します。シークレットを保存時に 0600 のアクセス権で保護でき、自己修復も行われます。環境変数（オプション B）は、ファイルへの書き込みが現実的でない CI／Docker／一時的な環境向けに用意されていますが、漏えいしやすいため、日常的な使用には推奨されません。

オプション A — 設定ファイル（推奨）

ウィザードを一度実行すれば、その後は設定を気にする必要はありません。

npx @yasuakiomokawa/oura-mcp configure

次の内容が書き込まれます。

~/.config/oura-mcp/config.json   # 0600, contains clientId / clientSecret / callbackPort
~/.config/oura-mcp/tokens.json   # 0600, contains the OAuth access / refresh tokens

読み込みのたびにアクセス権が再確認され、ほかの操作で変更されていた場合は 0600 に戻されます。

config.json のスキーマ：

{
  "schemaVersion": 1,
  "clientId": "...",
  "clientSecret": "...",
  "callbackPort": 54321
}

オプション B — 環境変数（CI／Docker のみ）

OURA_CLIENT_ID=...
OURA_CLIENT_SECRET=...        # must be set together with OURA_CLIENT_ID
OURA_CALLBACK_PORT=54321      # optional; safe to set in env regardless of Option A/B

サーバーの起動時に OURA_CLIENT_ID と OURA_CLIENT_SECRET の両方が設定されている場合、それらが使用され、config.env_credentials の警告が stderr に出力されます。

推奨しない理由：

• 同じユーザーとして実行されているすべてのプロセスが、/proc/<pid>/environ から process.env を読み取れます。
• サーバーが起動するすべての子プロセスに、環境変数が継承されます。
• process.env を取得するクラッシュダンプや可観測性ツールから、シークレットが漏えいします。
• シェルで OURA_CLIENT_SECRET=... npx ... と入力すると、シェルの履歴に残ります。

OURA_CALLBACK_PORT はシークレットではないため、どちらのモードでも環境変数で渡して問題ありません。

シークレットに args を使用しないでください

プロセスの引数は、ps／/proc/<pid>/cmdline を通じてほかのユーザーから見られます。MCP クライアントの設定の env ブロックを使用してください。

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@yasuakiomokawa/oura-mcp"],
      "env": { "OURA_CLIENT_ID": "...", "OURA_CLIENT_SECRET": "..." }
    }
  }
}

トラブルシューティング

• 「refresh_token expired」 — oura_authenticate（チャット内）または npx @yasuakiomokawa/oura-mcp configure（ターミナル内）を実行してください。
• ポート 54321 がすでに使用されています — OURA_CALLBACK_PORT=<other port> を設定し、Oura 開発者アプリのリダイレクト URI も一致するように更新してください。
• 「Path not found」 — oura_api_list_paths でパスを確認してください。よくある間違い：/v2/ プレフィックスの付け忘れ、daily_sleep のタイプミス。
• セットアップが「Waiting for authorization」で止まる — まだブラウザーで承認していないか、localhost に接続できるブラウザーセッションとは別のセッションで認証ページを開いています。
• ログが出力されない — 詳細な stderr ログを出力するには、OURA_LOG_LEVEL=debug を設定してください。

開発

git clone https://github.com/YasuakiOmokawa/oura-mcp.git
cd oura-mcp
npm install
npm test
npm run build

便利なスクリプト：

• npm run lint ／ npm run typecheck — Biome と TypeScript のチェック
• npm run test:coverage — V8 カバレッジを使用した Vitest
• npm run update:docs — Oura OpenAPI スキーマを再取得し、skills/oura-api-skill/references/ を再生成します

ライセンス

MIT