JinDaGe - oura-ring-mcp MCP Details

article

README

🚀 Oura MCP 服务器

这是一个 MCP 服务器，可将你的 Oura 智能戒指与 Claude 及其他 AI 助手相连接。它能为你提供关于睡眠、身体状态及活动的易读见解，而非仅仅是原始的 JSON 数据。

🚀 快速开始

1. 安装

npm install -g oura-ring-mcp

或者直接使用 npx（无需安装）：

npx oura-ring-mcp

2. 使用 Oura 进行身份验证

选项 A：个人访问令牌（更简单）

访问 cloud.ouraring.com/personal-access-tokens。
创建一个新令牌。
在你的 Claude 桌面版配置中设置 OURA_ACCESS_TOKEN（见下文）。

选项 B：OAuth CLI 流程

在 developer.ouraring.com 创建一个 OAuth 应用。
- 将重定向 URI 设置为 http://localhost:3000/callback。

运行认证流程：

export OURA_CLIENT_ID=your_client_id
export OURA_CLIENT_SECRET=your_client_secret
npx oura-ring-mcp auth

凭证将保存到 ~/.oura-mcp/credentials.json。

3. 配置 Claude 桌面版

添加到 claude_desktop_config.json： 使用个人访问令牌：

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

使用 OAuth（运行 npx oura-ring-mcp auth 后）：

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"]
    }
  }
}

服务器会从 ~/.oura-mcp/credentials.json 读取凭证。若要启用自动令牌刷新，请添加你的 OAuth 凭证：

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"],
      "env": {
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

重启 Claude 桌面版。需要 Node >=18。

✨ 主要特性

智能格式化 - 以小时/分钟显示时长，分数附带上下文说明（如“85 - 最佳”）。
睡眠分析 - 睡眠阶段、效率、心率变异性（HRV）及生物特征数据。
身体状态跟踪 - 恢复分数及各项因素的详细分析。
活动数据 - 步数、卡路里消耗及运动强度分析。
健康指标 - 心率、血氧饱和度（SpO2）、压力水平、心血管年龄。
智能分析 - 异常检测、相关性分析、趋势分析。
标签支持 - 对比有/无特定条件下的各项指标。

查看示例输出 — 了解 Claude 针对睡眠、身体状态、每周总结及智能分析所返回的内容。

💻 使用示例

基础用法

# 安装
npm install -g oura-ring-mcp

# 直接使用 npx
npx oura-ring-mcp

高级用法

# 使用 OAuth CLI 流程进行身份验证
export OURA_CLIENT_ID=your_client_id
export OURA_CLIENT_SECRET=your_client_secret
npx oura-ring-mcp auth

📚 详细文档

可以提出哪些问题？

日常检查：

“我昨晚睡得怎么样？”
“我今天恢复得足够进行锻炼吗？”
“我的身体现在有什么信号？”

模式与趋势：

“我在周末睡得更好吗？”
“我应该几点睡觉才能获得最佳睡眠？”
“我的心率变异性是在改善还是下降？”

相关性与见解：

“酒精会影响我的睡眠质量吗？”
“哪些因素能预测我睡眠最佳的夜晚？”
“运动时间如何影响我的恢复情况？”

对比：

“比较我本周和上周的睡眠情况”
“冥想后和不冥想时我的睡眠情况如何？”
“我开始服用镁之后有什么变化？”

异常情况：

“我的数据中是否有异常读数？”
“我昨天的身体状态为什么这么差？”
“找出我的指标异常的日子”

可用工具

数据检索

| 工具 | 描述 | |------|-------------| | get_sleep | 包含睡眠阶段、效率、心率、心率变异性的睡眠数据 | | get_daily_sleep | 每日睡眠分数及相关因素 | | get_readiness | 身体状态分数及恢复指标 | | get_activity | 步数、卡路里消耗、运动强度分析 | | get_workouts | 包含运动类型和强度的锻炼记录 | | get_sessions | 冥想和放松时段记录 | | get_heart_rate | 全天的心率读数 | | get_stress | 压力水平及恢复时间 | | get_spo2 | 血氧饱和度及呼吸干扰情况 | | get_tags | 用户创建的标签和笔记 |

智能分析

| 工具 | 描述 | |------|-------------| | detect_anomalies | 使用离群值检测找出异常读数 | | analyze_sleep_quality | 包含趋势、模式、睡眠债的睡眠分析 | | correlate_metrics | 找出健康指标之间的相关性 | | compare_periods | 比较本周和上周的数据 | | compare_conditions | 对比有/无特定标签时的指标 | | best_sleep_conditions | 找出影响优质/劣质睡眠的因素 | | analyze_hrv_trend | 心率变异性趋势及滚动平均值 |

资源

| 资源 | 描述 | |----------|-------------| | oura://today | 今日健康总结 | | oura://weekly-summary | 过去 7 天的平均值 | | oura://baseline | 30 天的平均值和正常范围 | | oura://monthly-insights | 30 天的分析，包含趋势和异常情况 | | oura://tag-summary | 你的标签及使用频率 |

提示

| 提示 | 描述 | |--------|-------------| | weekly-review | 全面的每周健康回顾 | | sleep-optimization | 找出实现最佳睡眠的因素 | | recovery-check | 你今天应该进行高强度训练还是休息？ | | compare-weeks | 本周与上周的比较 | | tag-analysis | 特定标签如何影响你的健康 |

远程部署（Railway）

部署 MCP 服务器以实现远程访问。该服务器通过 Oura 代理 OAuth，因此用户可直接使用其 Oura 账户进行身份验证，无需个人访问令牌。

1. 创建 Oura OAuth 应用

访问 Oura OAuth 应用。
创建一个新应用。
将 重定向 URI 设置为：https://your-app.railway.app/oauth/callback。
记录 客户端 ID 和 客户端密钥。

2. 部署

# 安装 Railway CLI
npm install -g @railway/cli

# 登录、初始化并部署
railway login
railway init
railway up

3. 设置环境变量

在 Railway 控制台中添加： | 变量 | 描述 | |----------|-------------| | OURA_CLIENT_ID | 来自你的 Oura OAuth 应用 | | OURA_CLIENT_SECRET | 来自你的 Oura OAuth 应用 | | NODE_ENV | production | | MCP_SECRET | (可选) 用于 Claude 桌面版的静态令牌 (openssl rand -base64 32) | | OURA_ACCESS_TOKEN | (可选) 若不使用 OAuth，可作为个人访问令牌的备用方案（需要 MCP_SECRET） |

Railway 会自动设置 PORT 和 RAILWAY_PUBLIC_DOMAIN。

4. 从 Claude.ai 连接

在 Claude.ai 中使用 连接器：

前往设置 > MCP 连接器 > 添加。
输入你的服务器 URL：https://your-app.railway.app（无需 /mcp）。
留空 OAuth 客户端 ID 和密钥（动态注册会处理）。
你将被重定向到 Oura 以授权访问你的数据。

5. 从 Claude 桌面版连接

对于 Claude 桌面版，使用 MCP_SECRET + OURA_ACCESS_TOKEN：

{
  "mcpServers": {
    "oura-remote": {
      "url": "https://your-app.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer your_mcp_secret_here"
      }
    }
  }
}

本地测试

# 使用 Oura OAuth（完整流程）
OURA_CLIENT_ID=your_id OURA_CLIENT_SECRET=your_secret pnpm start:http

# 仅使用静态密钥（需要 OURA_ACCESS_TOKEN）
OURA_ACCESS_TOKEN=your_pat MCP_SECRET=test-secret pnpm start:http

# 验证健康端点
curl http://localhost:3000/health

# 检查 OAuth 元数据（仅在设置了 OURA_CLIENT_ID 时可用）
curl http://localhost:3000/.well-known/oauth-authorization-server

# 测试认证请求（使用静态密钥）
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer test-secret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}'

📄 许可证

本项目采用 MIT 许可证。

贡献

有关架构细节和开发指南，请参阅 CLAUDE.md。

oura-ring-mcp