Oura Ring

Name: Oura Ring
Author: YasuakiOmokawa

本地服务

github.com/YasuakiOmokawa健康医疗124 周前更新

代码仓库

关于 Oura Ring

Oura Ring 是一个 MCP 服务，向兼容客户端提供 Oura Ring API v2 健康数据。配置向导负责 OAuth 设置，并可将服务写入检测到的客户端配置。

主要功能

01提供睡眠、活动、准备度、心率和锻炼数据
02列出支持的 API 路径
03执行支持分页的 API GET 请求
04通过向导配置 OAuth 和客户端条目
05以受限权限文件保存凭据和令牌

适用场景

01在 MCP 客户端查看睡眠和活动数据
02分页获取 Oura API 数据
03为兼容客户端设置 Oura OAuth
04刷新令牌过期后重新授权

MCP 相关

该 MCP 服务通过工具向兼容客户端提供 Oura API v2 端点。配置向导可将服务条目写入检测到的 MCP 客户端配置文件。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "yasuakiomokawa-oura": {
      "command": "npx",
      "args": [
        "-y",
        "@yasuakiomokawa/oura-mcp"
      ],
      "env": {
        "OURA_CLIENT_ID": "<OURA_CLIENT_ID>",
        "OURA_CLIENT_SECRET": "<OURA_CLIENT_SECRET>",
        "OURA_CALLBACK_PORT": "<OURA_CALLBACK_PORT>"
      }
    }
  }
}

启动命令npx -y @yasuakiomokawa/oura-mcp

需要配置的环境变量

OURA_CLIENT_IDOptional. Alternative to `npx oura-mcp configure`. Both OURA_CLIENT_ID and OURA_CLIENT_SECRET must be set together.

OURA_CLIENT_SECRET密钥Optional. See OURA_CLIENT_ID.

OURA_CALLBACK_PORTOAuth callback port (default 54321)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@yasuakiomokawa/oura-mcp0.2.13stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

oura-mcp

一个适用于 Oura Ring API v2 的模型上下文协议服务。它通过 OAuth 向兼容 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）提供睡眠、活动、准备度、心率和锻炼数据。

快速开始

npx @yasuakiomokawa/oura-mcp configure

向导会收集你的 Oura Client ID/Secret，引导你在浏览器中完成 OAuth，并将令牌保存到 ~/.config/oura-mcp/，同时在检测到的 MCP 客户端配置中添加 mcpServers.oura 条目。重启客户端后，即可使用下方的工具。

重新运行 configure 会预填已保存的 Client ID / 端口，因此你只需按 Enter 保留这些值。输入 --force 可清除已保存的状态并从头开始：

npx @yasuakiomokawa/oura-mcp configure --force

前置条件

在 https://cloud.ouraring.com/oauth/applications 注册 Oura 开发者应用
重定向 URI 必须完全一致：http://localhost:54321/callback （如果自定义 OURA_CALLBACK_PORT，则使用 http://localhost:<port>/callback）
启用所需的读取权限范围（Email、Personal info、Daily activity、Heart rate、Workout、Tag、Session、SpO2、Ring configuration、Stress、Heart health）
记下 Client ID 和 Client Secret——你将在 npx @yasuakiomokawa/oura-mcp configure 中输入它们

安装

根据你的客户端，有三种方式：

1. MCP Registry（支持自动发现的客户端）

发布到官方 MCP Registry后，支持的客户端即可从其界面安装 io.github.YasuakiOmokawa/oura-mcp。仍需运行一次向导步骤以获取 OAuth 令牌。

2. 手动配置（Claude Desktop / Claude Code / Cursor）

运行 npx @yasuakiomokawa/oura-mcp configure——向导的第 4 步会自动检测：

Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）
Claude Code（用户）：~/.claude.json
Claude Code（项目）：./.mcp.json
Cursor（用户）：~/.cursor/mcp.json
Cursor（项目）：./.cursor/mcp.json

每个检测到的文件都会在原子写入前备份为 <file>.bak.<ISO-timestamp>。

如需手动配置，请在客户端配置中添加：

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

3. 技能（可选）

配套的 oura-api-skill 提供逐端点参考资料和三种工作流方案（每周回顾 / 睡眠趋势 / 恢复情况检查）。可将其打包为 Claude Code 插件，或导入你的技能目录。

提供的工具

工具	用途
`oura_authenticate`	在浏览器中启动 OAuth 流程；返回 URL。用于 `refresh_token` 过期后。
`oura_auth_status`	检查当前令牌的有效性和到期时间。
`oura_clear_auth`	清除已存储的令牌。
`oura_api_list_paths`	列出所有支持的 `GET` 端点及其摘要。
`oura_api_get`	对 `/v2/...` 发起通用 `GET` 请求。通过 `max_pages`（1-20）自动分页，或在 `params` 中传入 `next_token`。

oura_api_get 会返回包含 { status, data, next_token, pages_fetched, has_more } 的 structuredContent。

配置

有两种方式。推荐使用配置文件（选项 A）——它会以 0600 权限在本地存储机密，并具备自我修复能力。环境变量（选项 B）适用于 CI / Docker / 临时环境，在这些环境中写入文件不切实际；但环境变量更容易泄露，不建议日常使用。

选项 A — 配置文件（推荐）

运行一次向导即可，无需再操心：

npx @yasuakiomokawa/oura-mcp configure

这会写入：

~/.config/oura-mcp/config.json   # 0600, contains clientId / clientSecret / callbackPort
~/.config/oura-mcp/tokens.json   # 0600, contains the OAuth access / refresh tokens

每次加载时都会重新检查权限；如果权限被其他操作更改，会将其恢复为 0600。

config.json 架构：

{
  "schemaVersion": 1,
  "clientId": "...",
  "clientSecret": "...",
  "callbackPort": 54321
}

选项 B — 环境变量（仅限 CI / Docker）

OURA_CLIENT_ID=...
OURA_CLIENT_SECRET=...        # must be set together with OURA_CLIENT_ID
OURA_CALLBACK_PORT=54321      # optional; safe to set in env regardless of Option A/B

服务启动时，如果同时设置了 OURA_CLIENT_ID 和 OURA_CLIENT_SECRET，就会使用它们，并向 stderr 输出 config.env_credentials 警告。

不推荐的原因：

任何以同一用户身份运行的进程都能通过 /proc/<pid>/environ 读取 process.env。
服务启动的每个子进程都会继承环境变量。
捕获 process.env 的崩溃转储和可观测性工具会泄露密钥。
在 shell 中输入 OURA_CLIENT_SECRET=... npx ... 会导致命令进入 shell 历史记录。

OURA_CALLBACK_PORT 不是密钥，在任何模式下都可以通过环境变量传入。

切勿将密钥用于 `args`

其他用户可以通过 ps / /proc/<pid>/cmdline 查看进程参数。请使用 MCP 客户端配置中的 env 区块：

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@yasuakiomokawa/oura-mcp"],
      "env": { "OURA_CLIENT_ID": "...", "OURA_CLIENT_SECRET": "..." }
    }
  }
}

故障排除

“refresh_token expired” — 运行 oura_authenticate（在聊天中），或在终端中运行 npx @yasuakiomokawa/oura-mcp configure。
端口 54321 已被占用 — 设置 OURA_CALLBACK_PORT=<other port>，并将 Oura 开发者应用中的重定向 URI 更新为匹配的值。
“Path not found” — 使用 oura_api_list_paths 验证路径。常见错误：缺少 /v2/ 前缀、daily_sleep 拼写错误。
设置卡在“Waiting for authorization” — 你尚未在浏览器中批准授权，或者授权页面是在无法访问 localhost 的另一个浏览器会话中打开的。
没有日志输出 — 设置 OURA_LOG_LEVEL=debug，以启用详细的 stderr 日志。

开发

git clone https://github.com/YasuakiOmokawa/oura-mcp.git
cd oura-mcp
npm install
npm test
npm run build

常用脚本：

npm run lint / npm run typecheck — Biome + TypeScript 检查
npm run test:coverage — 使用 V8 覆盖率的 Vitest
npm run update:docs — 重新获取 Oura OpenAPI 架构，并重新生成 skills/oura-api-skill/references/