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 应用