Oura Ring MCP

🚀 Oura Ring 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. 獲取 Oura 訪問令牌

若為個人使用，請創建個人訪問令牌：

1. 訪問 Oura Cloud 個人訪問令牌
2. 點擊“創建新的個人訪問令牌”
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 應用 中註冊一個 API 應用
2. 將 OURA_CLIENT_ID 和 OURA_CLIENT_SECRET 添加到 .env 文件中

💻 使用示例

本地測試

1. 測試服務器設置（無需進行 API 調用）：

npm test

2. 測試 API 連接性（需要你的 Oura 訪問令牌）：

npm run test:api

此命令將測試實際的 API 調用，以驗證你的憑證並顯示示例數據。

啟動 MCP 服務器

啟動 MCP 服務器，以便與 MCP 客戶端配合使用：

npm start

或者在開發模式下運行：

npm run dev

注意：服務器通過標準輸入輸出進行通信，等待 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 構建，主要特性如下：

身份驗證

• 使用個人訪問令牌進行 Bearer 令牌身份驗證
• 網絡鉤子操作需要 OAuth2 應用憑證

速率限制

• 每 5 分鐘內最多可進行 5000 次請求
• 建議使用網絡鉤子以減少 API 調用次數

數據類型

所有數據以結構化 JSON 格式返回，並使用 Zod 模式進行類型檢查和驗證。

錯誤處理

• 對 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 文檔
• 模型上下文協議
• 個人訪問令牌
• OAuth 應用