Oura Ring MCP

🚀 オウラリングMCPサーバー

このモデルコンテキストプロトコル（MCP）サーバーは、Oura API v2を通じて、Oura Ringの健康およびフィットネスデータへのアクセスを提供します。

✨ 主な機能

このMCPサーバーは、主要なOura Ringのデータタイプをすべてツールとして公開しています。

健康とフィットネスデータ

• 個人情報 - ユーザーのプロファイル情報（年齢、体重、身長、性別、タイムゾーン）
• 睡眠データ - 睡眠スコア、睡眠段階、睡眠に影響する要因
• 活動データ - 歩数、消費カロリー、活動レベル、MET分
• 体調データ - 日々の体調スコアとその要因
• 心拍数 - タイムスタンプとデータソース付きの心拍数測定値

日次サマリー

• 日次活動 - スコアと指標を含む日次活動のサマリー
• 日次睡眠 - スコアと要因を含む日次睡眠のサマリー
• 日次体調 - 体温データを含む日次体調のサマリー
• 日次ストレス - 日々のストレスレベルと回復指標

セッションとワークアウト

• ワークアウト - 活動タイプ、持続時間、消費カロリー、距離を含む運動セッション
• セッション - 呼吸法、瞑想、昼寝、リラックスセッション
• タグ - ユーザーが作成したタグとメタデータ付きの拡張タグ

設定と時間データ

• 睡眠時間 - 就寝時間と起床時間のデータ
• 休息モード期間 - 休息モードが有効な期間
• リング設定 - リングの設定とプリファレンス

ウェブフック（高度な機能）

• ウェブフック管理 - リアルタイムのデータ更新のためのウェブフックサブスクリプションの作成、一覧表示、削除

📦 インストール

1. このリポジトリをクローンします：

git clone <repository-url>
cd oura-ring-mcp

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

📚 ドキュメント

1. オウラアクセストークンを取得する

個人使用の場合は、個人用アクセストークンを作成します：

1. Oura Cloud Personal Access Tokensにアクセスします。
2. 「Create New Personal Access Token」をクリックします。
3. 生成されたトークンをコピーします。

2. 環境設定

プロジェクトのルートに.envファイルを作成します：

# 必須：あなたのOura Ringの個人用アクセストークン
OURA_ACCESS_TOKEN=your_personal_access_token_here

# オプション：ウェブフック機能のみに必要
OURA_CLIENT_ID=your_client_id_here
OURA_CLIENT_SECRET=your_client_secret_here

# オプション：デフォルトのAPIベースURLを上書きする（通常は必要ありません）
# OURA_BASE_URL=https://api.ouraring.com

3. ウェブフック機能の使用（オプション）

リアルタイムのデータ更新にウェブフックを使用する場合は：

1. Oura Cloud OAuth ApplicationsでAPIアプリケーションを登録します。
2. OURA_CLIENT_IDとOURA_CLIENT_SECRETを.envファイルに追加します。

💻 使用例

ローカルでのテスト

1. サーバーのテストセットアップ（API呼び出し不要）：

npm test

2. API接続性のテスト（オウラアクセストークンが必要）：

npm run test:api

これにより、実際のAPI呼び出しがテストされ、資格情報が検証され、サンプルデータが表示されます。

MCPサーバーの起動

MCPクライアントで使用するためにMCPサーバーを起動します：

npm start

または、開発モードで実行します：

npm run dev

注意：サーバーはstdioトランスポートで実行され、MCPプロトコルメッセージを待機します。サーバーとやり取りするには、MCPクライアント（Claude Desktop、Continue、またはその他のMCP対応ツールなど）が必要です。

利用可能なツール

個人情報

• get_personal_info - ユーザーの個人情報を取得する

睡眠と体調

• get_sleep - オプションの日付範囲で睡眠データを取得する
• get_daily_sleep - 日次睡眠のサマリーを取得する
• get_readiness - 体調データを取得する
• get_daily_readiness - 日次体調のサマリーを取得する

活動と運動

• get_activity - 活動データを取得する
• get_daily_activity - 日次活動のサマリーを取得する
• get_workouts - 運動セッションを取得する
• get_heart_rate - 心拍数測定値を取得する

セッションと健康

• get_sessions - 呼吸法、瞑想、昼寝のセッションを取得する
• get_daily_stress - 日次ストレスと回復データを取得する
• get_tags - ユーザーが作成したタグを取得する
• get_enhanced_tags - メタデータ付きの拡張タグを取得する

時間と設定

• get_sleep_time - 就寝時間と起床時間のデータを取得する
• get_rest_mode_periods - 休息モード期間を取得する
• get_ring_configuration - リングの設定を取得する

ウェブフック（高度な機能）

• get_webhook_subscriptions - アクティブなウェブフックサブスクリプションの一覧を取得する
• create_webhook_subscription - 新しいウェブフックサブスクリプションを作成する
• delete_webhook_subscription - ウェブフックサブスクリプションを削除する

日付範囲パラメータ

ほとんどのツールは、オプションの日付範囲パラメータを受け付けます：

• start_date - YYYY-MM-DD形式の開始日
• end_date - YYYY-MM-DD形式の終了日
• next_token - 大規模なデータセットのページネーショントークン

例：

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

🔧 技術詳細

このMCPサーバーは、Oura API v2をベースに構築されています。主な特徴は以下の通りです。

認証

• 個人用アクセストークンを使用したベアラートークン認証を使用します。
• ウェブフック操作にはOAuth2アプリケーションの資格情報が必要です。

レート制限

• 5分間に5000回のリクエストが許可されます。
• ウェブフックを使用することでAPI呼び出しを最小限に抑えることをおすすめします。

データタイプ

すべてのデータは、Zodスキーマを使用して適切な型付けと検証が行われた構造化JSONとして返されます。

エラーハンドリング

• APIエラー、ネットワーク問題、無効なレスポンスに対する包括的なエラーハンドリングが行われます。
• 可能な場合は、ステータスコード付きの詳細なエラーメッセージが表示されます。

ウェブフック

ウェブフックは、Ouraデータが変更されたときにリアルタイムの通知を提供します。最新のデータが必要なアプリケーションには、この方法がおすすめです。

ウェブフックの設定

1. OURA_CLIENT_IDとOURA_CLIENT_SECRETが設定されていることを確認します。
2. 以下のパラメータを使用してcreate_webhook_subscriptionツールを使用します：
   • callback_url - あなたのエンドポイントURL（HTTPSである必要があります）
   • verification_token - 検証用の秘密トークン
   • event_type - イベントのタイプ（'create'、'update'、'delete'）
   • data_type - データのタイプ（'sleep'、'activity'など）

ウェブフックのデータタイプ

• tag - ユーザータグ
• enhanced_tag - メタデータ付きの拡張タグ
• workout - 運動セッション
• session - 呼吸法、瞑想、昼寝のセッション
• sleep - 睡眠データ
• daily_sleep - 日次睡眠のサマリー
• daily_readiness - 日次体調のサマリー
• daily_activity - 日次活動のサマリー
• daily_stress - 日次ストレスデータ

開発

プロジェクト構造

src/
├── types.ts          # TypeScriptの型定義とZodスキーマ
├── oura-client.ts    # Oura APIクライアントの実装
├── server.ts         # MCPサーバーの実装
└── index.ts          # メインエントリーポイント

test/
├── test.ts           # 基本的なサーバーインスタンス化テスト
├── manual-test.ts    # 実際の資格情報を使用したAPI接続性テスト
└── debug-test.ts     # 生のAPIレスポンスのデバッグツール

ビルド

npm run build

テスト

# サーバーのインスタンス化テスト（API呼び出しなし）
npm test

# あなたの資格情報を使用した実際のAPI接続性のテスト
npm run test:api

リント

npm run lint

トラブルシューティング

一般的な問題

「無効または期限切れの認証トークン」

• OURA_ACCESS_TOKENが正しいことを確認します。
• トークンが期限切れになっていないことを確認します。
• 正しいOuraアカウントの個人用アクセストークンを使用していることを確認します。

「アクセスが禁止されました」（403エラー）

• あなたのOuraサブスクリプションが期限切れになっている可能性があります。
• 一部のデータタイプには、有効なOuraサブスクリプションが必要です。

レート制限超過（429エラー）

• 5分間に5000回以上のリクエストを送信しています。
• ウェブフックを使用してAPI呼び出しを減らすことを検討してください。
• アプリケーションに適切なレート制限を実装してください。

ウェブフックの検証に失敗しました

• ウェブフックエンドポイントが検証チャレンジを適切に処理していることを確認します。
• verification_tokenが提供したものと一致することを確認します。
• エンドポイントが正しい形式でチャレンジに応答することを確認します。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

コントリビューション

コントリビューションを歓迎します！改善点については、コントリビューションガイドラインを読んで、プルリクエストを送信してください。

リンク

• Oura Ring
• Oura API Documentation
• Model Context Protocol
• Personal Access Tokens
• OAuth Applications