Oura Ring (read-only)

Oura Ring MCP 服务（只读）

向 Claude、Cursor、VS Code 或任何 MCP 客户端询问你的 Oura Ring 准备度、睡眠、HRV、活动、压力和心率信息，同时不会赋予它修改数据的能力。

“我昨晚睡得怎么样？为什么准备度只有 64？” “比较一下过去 30 天的 HRV 和最低心率。” “显示昨晚的睡眠阶段和心率曲线。” “标记饮酒的日子之后，我的准备度会下降吗？”

（安装前或安装后，先运行一次 auth 步骤。）

为什么选择此服务

• 强制只读。 Oura 的 API 没有用于写入你数据的端点，而此客户端的限制更严格：它只能发送 GET 请求，拒绝 /v2/usercollection/ 以外的任何 URL，不会触及 webhook API，并且每个工具都带有 readOnlyHint: true。否则测试会导致构建失败。
• 一次调用回答完整问题。 get_daily_overview 会同时返回某一天的准备度、睡眠、小睡、活动、压力、韧性、SpO2、锻炼和标签。get_trends 会返回每日数据表，以及最多 90 天的平均值和准备度区间。
• 适合模型处理的输出。 使用小时、分钟、千米和本地时间，而非秒和米，输出紧凑 JSON；睡眠图以阶段片段表示；心率汇总为多个区间。传入 raw: true 可获取 Oura 的原始对象。
• 优雅降级。 如果你在 Oura 的授权页面取消勾选某种数据类型，组合工具会将其列在 unavailable 下，而不会报错。
• 令牌留在你的设备上。 使用你自己的 Oura API 应用、基于 PKCE 的 OAuth、权限为 0600 的令牌文件，并安全处理 Oura 的一次性刷新令牌。没有第三方服务，也没有遥测。
• 无需账户即可试用。 设置 OURA_SANDBOX=1 即可提供 Oura 的公开示例数据。

快速开始

你需要 Node.js 20.11+ 和一个 Oura 账户。（Oura 已于 2025 年 12 月停用个人访问令牌，因此只能通过 OAuth 访问。）

1. 创建 Oura API 应用（2 分钟）

1. 打开 cloud.ouraring.com/oauth/applications 并创建一个新应用。
2. 将 Redirect URI 设为 http://localhost:8787/callback。
3. 复制 Client ID 和 Client Secret。

无需 Oura 批准，应用最多可供 10 位用户使用，个人使用绰绰有余。

2. 连接你的 Oura 账户

npx -y @royreznik/oura-ring-mcp auth

根据提示粘贴你的 Client ID 和 Client Secret（输入密钥时不会显示）。浏览器会打开 Oura 的授权页面；保留所有数据类型的勾选状态并批准。令牌会保存到 ~/.config/oura-ring-mcp/tokens.json，之后会自动刷新。

（对于脚本，请设置 OURA_CLIENT_ID 和 OURA_CLIENT_SECRET，而不是回答提示。）

3. 将其添加到你的 MCP 客户端

/plugin marketplace add royreznik/oura-ring-mcp
/plugin install oura@oura-ring-mcp

claude mcp add oura --scope user -- npx -y @royreznik/oura-ring-mcp

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@royreznik/oura-ring-mcp"]
    }
  }
}

{
  "servers": {
    "oura": { "type": "stdio", "command": "npx", "args": ["-y", "@royreznik/oura-ring-mcp"] }
  }
}

[mcp_servers.oura]
command = "npx"
args = ["-y", "@royreznik/oura-ring-mcp"]

docker build -t oura-ring-mcp https://github.com/royreznik/oura-ring-mcp.git
docker run -i --rm -v ~/.config/oura-ring-mcp:/home/node/.config/oura-ring-mcp oura-ring-mcp

然后询问：“给我看看今天的 Oura 概览。”

无需账户即可试用

claude mcp add oura-sandbox --env OURA_SANDBOX=1 -- npx -y @royreznik/oura-ring-mcp

沙盒模式会提供 Oura 的公开示例数据。无需授权，也不会使用个人数据。

工具

列表工具接受 start / end（YYYY-MM-DD，含首尾日期）、days 快捷参数和 next_token。详情请参阅**工具参考**。

配置

oura-ring-mcp            Start the MCP server on stdio (what your MCP client runs)
oura-ring-mcp auth       Connect your Oura account (opens your browser)
oura-ring-mcp status     Check the stored connection
oura-ring-mcp logout     Delete the locally stored tokens
oura-ring-mcp --version

“今天”根据你电脑的时区计算，该时区应与 Oura 应用使用的时区一致。

隐私与安全

• oura-ring-mcp 只会与 api.ouraring.com 通信（以及在 auth 期间通过浏览器访问 cloud.ouraring.com）。不收集遥测数据，也不使用中间服务。
• 令牌和客户端密钥仅存储在一个只有你的用户才能读取的文件中（0600）。它们绝不会被记录日志或由工具返回。
• **你的 MCP 客户端会将工具结果发送给其大模型。**你询问的健康数据会根据该模型提供商的条款与其共享。
• 如需断开连接，请运行 oura-ring-mcp logout。如需彻底撤销访问权限，请在 cloud.ouraring.com/oauth/applications 删除应用，或在你的 Oura 账户中撤销访问权限。

详情：PRIVACY.md、SECURITY.md。

身份验证的工作原理

• 使用 OAuth 2 授权码流程，配合 PKCE（S256）和随机 state，由仅监听回环地址的回调服务捕获。
• Oura 刷新令牌只能使用一次。oura-ring-mcp 会在令牌过期前不久刷新（收到 401 时也会刷新），并通过锁文件确保同一台设备上的多个客户端（例如 Claude Desktop 和 Claude Code）不会同时刷新，一次只进行一个刷新操作，同时以原子方式写入新令牌。如果写入失败，新令牌会保留在内存中，因此磁盘空间用尽也不会导致你被注销。
• 对速率限制（429，并遵循 Retry-After）、服务器错误、超时（30s）和网络错误进行退避重试。在客户端取消请求会停止其发出的 Oura 请求。

故障排除

npx -y @royreznik/oura-ring-mcp status

开发

npm install
npm test                 # unit, MCP integration, end-to-end and packaging tests (no network)
npm run smoke:sandbox    # every tool against Oura's live sandbox API
npm run smoke:live       # every tool against your account (after auth); prints only counts
npm run inspect          # MCP Inspector

请参阅 CONTRIBUTING.md。唯一不可妥协的规则：oura-ring-mcp 始终保持只读。

致谢与法律声明

架构、身份验证和测试方法改编自 Oryan Omer 的 whoop-mcp（MIT）。

MIT © Roy Reznik。非官方项目，与 Oura Health Oy 无关，也未获得其认可。“Oura”是 Oura Health Oy 的商标。本文内容不构成医疗建议。