AI导哈

Oura Ring健康数据服务器

一个为Oura Ring API V2提供的模型上下文协议(MCP)服务器，通过AI助手访问睡眠、活动、心率等健康数据。

  • by trenerok
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 trenerok/oura-mcp-server

使用说明

Oura环MCP服务器

一个全面的模型上下文协议（MCP）服务器 欧拉戒指 API V2。通过Claude、ChatGPT或Cursor IDE等人工智能助手从Oura Ring访问睡眠、活动、准备状态、心率、压力和其他健康数据。

安全第一：此服务器实现 仅限只读操作 用户数据。您的健康信息无法修改。

这是什么？

此MCP服务器允许AI助手访问您的Oura Ring健康数据。连接后，您可以提出以下问题：

  • “我昨晚睡得怎么样？”
  • “我本周的准备得分是多少？”
  • “显示我的心率趋势”
  • “分析我的压力模式”

关键词：Oura Ring，MCP服务器，模型上下文协议，睡眠跟踪，健康数据，可穿戴API，AI集成，Claude，ChatGPT，Cursor

目录

Oura戒指是什么？

欧拉戒指 是一个智能戒指，可以跟踪：

  • 睡眠 -睡眠阶段（深度、轻度、快速眼动）、睡眠质量、时间
  • 活动 -一天中的步数、卡路里、运动量
  • 准备就绪 -基于睡眠、活动和身体信号的恢复评分
  • 心率 -连续心率和心率变异性
  • 体温 -皮肤温度偏差
  • 压力 -日间压力和恢复模式
  • SpO2 -血氧饱和度

此MCP服务器通过以下方式提供对所有这些数据的访问 Oura API V2.

特性

特性 描述
37 MCP工具 全面覆盖所有Oura API V2端点
按设计只读 无法修改用户数据
OAuth2身份验证 基于令牌的安全身份验证，支持刷新令牌
自动令牌刷新 自动刷新过期的访问令牌
沙盒支持 在使用真实数据之前使用模拟数据进行测试
速率限制 内置速率限制和指数回退
令牌消毒 访问令牌永远不会在日志或错误中公开

快速开始

1.克隆和安装

git clone https://github.com/trenerok/oura-mcp-server.git
cd oura-mcp-server
npm install

2.获取OAuth2凭据

看 获取访问令牌 在......下面

3.建造

npm run build

4.配置MCP客户端

看 MCP 客户端安装 适用于Claude Desktop、Cursor IDE或其他客户端。

获取访问令牌

Oura使用OAuth2进行身份验证。个人访问令牌于2025年12月被弃用。

步骤1：创建OAuth2应用程序

  1. 首选 Oura云应用
  2. 点击“新建应用程序”
  3. 填写必填字段：
    • 显示名称：您的应用程序名称（例如“我的MCP服务器”）
    • 描述：简要说明
    • 网站：您的网站或GitHub仓库URL
    • 隐私政策：URL（可以是您的GitHub仓库供个人使用）
    • 服务条款：URL（可以是您的GitHub仓库供个人使用）
    • 重定向URI: http://localhost:8080/callback
  4. 选择所有 范围 您想访问
  5. 点击“创建应用程序”
  6. 复制您的 客户端ID 和 客户端密钥

步骤2：获取访问令牌

使用附带的辅助脚本：

node scripts/get-token.js YOUR_CLIENT_ID YOUR_CLIENT_SECRET

这将：

  1. 打开浏览器以授权应用程序
  2. 将授权码替换为令牌
  3. 显示您的访问令牌和刷新令牌

步骤3：保存您的代币

将令牌添加到MCP配置中（请参阅 MCP 客户端安装).

配置

环境变量

变量 必填 描述
OURA_ACCESS_TOKEN 是* OAuth2用户数据访问令牌
OURA_REFRESH_TOKEN 否 刷新令牌以自动续订令牌
OURA_CLIENT_ID 否** OAuth2应用程序客户端ID
OURA_CLIENT_SECRET 无** OAuth2应用程序客户端机密
OURA_USE_SANDBOX 否 设置为 true 用于沙箱/模拟数据

*用户数据端点需要 **令牌刷新和webhook管理所需

自动令牌刷新

如果你提供 OURA_REFRESH_TOKEN, OURA_CLIENT_ID，以及 OURA_CLIENT_SECRET，服务器将在访问令牌过期时（通常在24小时后）自动刷新您的访问令牌。

MCP 客户端安装

克劳德桌面版

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oura": {
      "command": "node",
      "args": ["/absolute/path/to/oura-mcp-server/dist/index.js"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_access_token",
        "OURA_REFRESH_TOKEN": "your_refresh_token",
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

光标IDE

添加到 .cursor/mcp.json 在您的项目目录中：

{
  "mcpServers": {
    "oura": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_access_token",
        "OURA_REFRESH_TOKEN": "your_refresh_token",
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

其他MCP客户端

为您的客户端使用具有适当配置文件格式的类似配置。

可用工具（共37个）

按类别概述

类别 计数 工具
个人信息 1 用户资料（年龄、体重、身高）
睡眠 6 睡眠时间、每日评分、就寝时间建议
活动 2 日常活动、步数、消耗的卡路里
健康指标 14 心率、准备状态、SpO2、压力、恢复力、心血管年龄、最大摄氧量
锻炼 4 锻炼课程、冥想/呼吸课程
标签 4 用户创建的标签和增强标签
设备 4 环形配置，休息模式时段
网络钩子 6 Webhook订阅管理

完整工具清单

个人信息（1个工具）

工具 说明
get_personal_info 获取用户资料：年龄、体重、身高、生物性别、电子邮件

睡眠（6工具）

工具 说明
get_sleep 详细的睡眠阶段（深睡、浅睡、快速眼动）、心率、心率
get_sleep_by_id 按文档ID划分的单次睡眠会话
get_daily_sleep 每日睡眠评分及贡献者细分
get_daily_sleep_by_id 按ID列出的单日睡眠记录
get_sleep_time 最佳就寝时间建议
get_sleep_time_by_id 按ID列出的单个睡眠时间文档

活动（2个工具）

工具 说明
get_daily_activity 每日步数、卡路里、活动时间、MET分钟数
get_daily_activity_by_id 按ID列出的单个日常活动文档

健康指标（14种工具）

工具 说明
get_heart_rate 心率时间序列（带时间戳的BPM）
get_daily_readiness 贡献者的每日准备度得分
get_daily_readiness_by_id 按ID列出的单一准备文件
get_daily_spo2 血氧饱和度（SpO2）数据
get_daily_spo2_by_id 按ID列出的单一SpO2文件
get_daily_stress 日常压力水平和恢复时间
get_daily_stress_by_id 按ID列出的单应力文档
get_daily_resilience 每日弹性得分
get_daily_resilience_by_id 按ID列出的单一弹性文件
get_daily_cardiovascular_age 血管年龄估计
get_daily_cardiovascular_age_by_id 按ID列出的单一心血管年龄文件
get_vo2_max 最大摄氧量估计值（心血管健康）
get_vo2_max_by_id 按ID列出的单个最大VO2文档

锻炼（4个工具）

工具 说明
get_workouts 锻炼时间（活动类型、卡路里、距离、持续时间）
get_workout_by_id 按ID列出的单个锻炼文档
get_sessions 使用心率变异性数据进行冥想和呼吸训练
get_session_by_id 按ID列出的单会话文档

标签（4个工具）

工具 说明
get_tags 用户创建的用于跟踪行为的标签
get_tag_by_id 按ID标记的单标签文档
get_enhanced_tags 具有元数据和时间范围的增强标签
get_enhanced_tag_by_id 按ID显示单个增强标记文档

设备（4个工具）

工具 说明
get_ring_configuration 戒指详细信息：颜色、尺寸、固件、硬件类型
get_ring_configuration_by_id 按ID进行单环配置
get_rest_mode_periods 休息模式激活历史
get_rest_mode_period_by_id 按ID划分的单次休息模式时段

Webhooks（6个工具）-需要客户端凭据

工具 说明
list_webhook_subscriptions 列出所有webhook订阅
get_webhook_subscription 按ID获取特定的webhook
create_webhook_subscription 创建新的webhook订阅
update_webhook_subscription 更新现有webhook
delete_webhook_subscription 删除webhook订阅
renew_webhook_subscription 到期前续订webhook

工具参考

公共参数

日期范围参数（大多数工具）

参数 格式 必填 说明
start_date YYYY-MM-DD 否 日期范围的开始
end_date YYYY-MM-DD 否 日期范围结束
next_token string 否 下一页的分页标记

DateTime参数（仅心率）

参数 格式 必填 说明
start_datetime ISO 8601 否 开始日期时间（例如。， 2024-01-01T00:00:00Z)
end_datetime ISO 8601 否 结束日期时间
next_token string 否 分页标记

示例响应

个人信息

{
  "id": "abc123",
  "age": 35,
  "weight": 75.5,
  "height": 1.80,
  "biological_sex": "male",
  "email": "user@example.com"
}

每日睡眠

{
  "data": [
    {
      "id": "sleep123",
      "day": "2024-01-15",
      "score": 85,
      "contributors": {
        "deep_sleep": 80,
        "efficiency": 90,
        "latency": 85,
        "rem_sleep": 75,
        "restfulness": 82,
        "timing": 95,
        "total_sleep": 88
      },
      "timestamp": "2024-01-15T00:00:00.000+00:00"
    }
  ],
  "next_token": null
}

日常准备

{
  "data": [
    {
      "id": "ready123",
      "day": "2024-01-15",
      "score": 78,
      "contributors": {
        "activity_balance": 85,
        "body_temperature": 100,
        "hrv_balance": 72,
        "previous_day_activity": 80,
        "previous_night": 75,
        "recovery_index": 90,
        "resting_heart_rate": 82,
        "sleep_balance": 70
      },
      "temperature_deviation": 0.1,
      "timestamp": "2024-01-15T00:00:00.000+00:00"
    }
  ],
  "next_token": null
}

心率

{
  "data": [
    {
      "bpm": 62,
      "source": "awake",
      "timestamp": "2024-01-15T08:30:00+00:00"
    },
    {
      "bpm": 58,
      "source": "rest",
      "timestamp": "2024-01-15T08:35:00+00:00"
    }
  ],
  "next_token": null
}

对于AI代理

本节为使用此MCP服务器的AI代理提供结构化指导。

服务器功能

  • 数据访问：只读访问所有Oura Ring健康数据
  • 认证：具有自动刷新功能的OAuth2承载令牌
  • 实时数据：从Oura API实时获取数据
  • 分页：大型数据集返回 next_token 用于分页

AI代理的快速入门

  1. 验证连接：呼叫 get_personal_info 第一
  2. 使用日期范围：始终指定 start_date 限制数据
  3. 处理空数据：空数组表示该期间没有数据
  4. 检查空值：如果不可用，许多字段可能为空

推荐工作流程

健康仪表盘

1. get_personal_info() → Get user profile
2. get_daily_readiness(start_date: "<7 days ago>") → Weekly readiness trend
3. get_daily_sleep(start_date: "<7 days ago>") → Weekly sleep scores
4. get_daily_activity(start_date: "<7 days ago>") → Weekly activity
5. get_daily_stress(start_date: "<7 days ago>") → Weekly stress patterns

睡眠分析

1. get_daily_sleep(start_date: "<30 days ago>") → Monthly sleep scores
2. get_sleep(start_date: "<7 days ago>") → Detailed sleep sessions with stages
3. get_sleep_time(start_date: "<7 days ago>") → Bedtime recommendations

体能评估

1. get_daily_activity(start_date: "<30 days ago>") → Activity trends
2. get_workouts(start_date: "<30 days ago>") → Workout history
3. get_vo2_max(start_date: "<30 days ago>") → Cardiovascular fitness
4. get_heart_rate(start_datetime: "<today>T00:00:00Z") → Today's heart rate

压力与恢复

1. get_daily_stress(start_date: "<7 days ago>") → Stress levels
2. get_daily_resilience(start_date: "<7 days ago>") → Resilience scores
3. get_daily_readiness(start_date: "<7 days ago>") → Recovery status

关键指标说明

度量 范围 含义
睡眠评分 0-100 整体睡眠质量（>85=最佳）
准备度得分 0-100 恢复水平（>85=准备活动）
活动评分 0-100 每日运动目标进度
压力（高） 秒 高压力状态下的时间
恢复（高） 秒 恢复/休息状态的时间
心率变异性 ms 心率变异性（越高=恢复越好）
休息人力资源 bpm 静息心率（较低=健康状况较好）

错误处理

错误 原因 解决方案
Access token not configured 缺少OURA_ACCESS_TOKEN 将令牌添加到配置中
401 Unauthorized 令牌已过期 如果提供了刷新令牌，服务器将自动刷新
403 Forbidden 范围未授权 使用所需范围重新授权
429 Rate Limit 请求太多 服务器自动重试并回退
空 data: [] 日期范围没有数据 尝试其他日期范围

重要说明

  • 日期格式：使用 YYYY-MM-DD 对于日期
  • 日期时间格式：使用ISO 8601 get_heart_rate （例如。， 2024-01-15T00:00:00Z)
  • 时区：数据以用户的时区返回
  • 分页：如果 next_token 不为空，有更多数据可用
  • 空值：如果戒指没有磨损或数据不可用，则字段可能为空

速率限制

服务器实现自动速率限制 我们的API文件.

限制 值
请求： 每5分钟5000
算法 带充值功能的代币桶
重试 指数回退（1s→ 2s → 4s、 最大30秒）
最大重试次数 3次尝试

项目结构

oura-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── client.ts          # Oura API client with auth & rate limiting
│   ├── rate-limiter.ts    # Token bucket rate limiter
│   ├── types.ts           # TypeScript type definitions
│   └── tools/
│       ├── index.ts       # Tool aggregator
│       ├── personal-info.ts
│       ├── sleep.ts
│       ├── activity.ts
│       ├── health.ts
│       ├── workout.ts
│       ├── tags.ts
│       ├── device.ts
│       └── webhook.ts
├── scripts/
│   └── get-token.js       # OAuth2 token helper
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── LICENSE
├── CHANGELOG.md
└── README.md

安全

最佳实践

  1. 从不提交代币 --使用环境变量
  2. 使用刷新令牌 --启用自动令牌续订
  3. 沙盒测试 --设置 OURA_USE_SANDBOX=true 为了发展
  4. 限制范围 --仅请求您需要的OAuth2作用域

安全特性

  • 已清除所有错误消息中的访问令牌
  • 只读API访问（不能修改数据）
  • 自动令牌刷新（无需手动令牌管理）
  • 利率限制防止API滥用

故障排除

常见问题

问题 解决方案
Cannot find module 快跑 npm run build
Access token not configured 添加 OURA_ACCESS_TOKEN 转到env
401 Unauthorized 令牌已过期；添加刷新令牌或获取新令牌
403 Forbidden 缺少OAuth2作用域；重新授权应用程序
返回空数据 检查日期范围；确保环同步数据
Token not authorized for scope 使用所需作用域重新创建OAuth2应用程序

获取帮助

  1. 检查 Oura API文档
  2. 在GitHub上打开一个问题
  3. 检查 MCP协议文件

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild)
npm run dev

# Run server
npm start

# Clean build
npm run clean

贡献

  1. 克隆该仓库
  2. 创建要素分支： git checkout -b feature/my-feature
  3. 进行更改和测试： npm run build
  4. 承诺： git commit -m "Add my feature"
  5. 推： git push origin feature/my-feature
  6. 创建拉取请求

api参考

许可证

MIT许可证——见 许可证 文件。

免责声明

本软件按“原样”提供，不提供保修。本项目不隶属于Oura Health Oy或得到其认可。

不是医疗建议。 Oura Ring数据仅供参考，不应用于医疗诊断或治疗。

相关 MCP