oura-ring-mcp-server

oura-ring-mcp-server

一个适用于 Oura Ring API v2 的模型上下文协议服务。 将 Claude（或任何 MCP 客户端）连接到你的 Oura 数据，即可询问有关睡眠、准备度、活动、心率、锻炼等方面的问题。

使用 somamcp（遥测 + 内省）、functype（类型化错误处理）和 zod 构建。

设计

该服务没有为每个端点提供一个工具，而是通过 collection 参数提供一个整合的 oura_data 工具。 这样可以在覆盖 Oura 的所有 usercollection 端点的同时，保持工具架构精简（降低令牌成本）。该工具会验证你传入的参数对于所选集合是否合法，并在参数不合法时返回可操作的提示。

要求

• Node.js 24+（在 .nvmrc 中固定）

• 一个 Oura OAuth2 应用——在 cloud.ouraring.com/oauth/applications 注册，以获取 客户端 ID 和密钥。将重定向 URI 设置为 http://localhost:8080/callback，并启用所需的读取权限范围。默认情况下会请求完整权限集—— email personal daily heartrate tag workout session spo2 ring_configuration stress heart_health—— 因此所有集合都能正常工作（其中 heart_health 尤其是 vO2_max 和 daily_cardiovascular_age 的必要权限）。

  Oura 已于 2025 年 12 月停止签发新的个人访问令牌，因此新设置应使用 OAuth2。此前签发的 PAT 仍然有效——请参阅身份验证。

身份验证

该服务使用 OAuth2 访问令牌向 Oura 进行身份验证，并会自动刷新令牌。你只需使用内置的 login 命令授权一次：

# with OURA_CLIENT_ID and OURA_CLIENT_SECRET set in the environment
npx -y oura-ring-mcp-server login

此命令会打开浏览器供你授权，在 http://localhost:8080/callback 接收重定向，并将令牌写入 ~/.config/oura-ring-mcp/tokens.json（可通过 OURA_TOKEN_STORE 覆盖）。Oura 的刷新令牌只能使用一次，因此之后由服务负责管理并轮换存储中的令牌——你无需将刷新令牌放入环境变量。MCP 服务启动时会读取该存储；只有刷新令牌被撤销时才需要重新运行 login。

**旧版 PAT：**如果你仍有有效的个人访问令牌，请改为设置 OURA_API_KEY，并跳过 OAuth 设置。如果两者都已配置，将优先使用 OAuth。

用法

Claude Desktop / Claude Code

将以下内容添加到你的 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "oura-ring-mcp-server"],
      "env": {
        "OURA_CLIENT_ID": "your-oauth-client-id",
        "OURA_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

这会通过 stdio 运行服务，这是大多数 MCP 客户端所需的方式。请先运行一次 login（参阅身份验证），以创建令牌存储。

配置

环境变量	必填	默认值	描述
OURA_CLIENT_ID	用于 OAuth	—	Oura OAuth2 客户端 ID。
OURA_CLIENT_SECRET	用于 OAuth	—	Oura OAuth2 客户端密钥。
OURA_API_KEY	用于旧版 PAT	—	旧版个人访问令牌（Bearer）。可替代 OAuth 凭据对。
OURA_REDIRECT_URI	否	http://localhost:8080/callback	login 的重定向 URI；必须与 Oura 应用注册信息匹配。
OURA_SCOPES	否	完整读取范围集（参见要求）	login 期间请求的、以空格分隔的范围。
OURA_TOKEN_STORE	否	~/.config/oura-ring-mcp/tokens.json	OAuth 令牌存储路径。
OURA_SANDBOX	否	false	使用 Oura 的 /sandbox/ 演示数据，而非真实数据。
TRANSPORT_TYPE	否	stdio	stdio 或 httpStream。
PORT	否	3000	httpStream 传输的端口。
HOST	否	0.0.0.0	httpStream 传输的主机。
OURA_TELEMETRY_FILE	否	—	将 NDJSON 遥测事件写入此文件路径（适用于任何传输方式）。
OURA_TELEMETRY_CONSOLE	否	true	控制台遥测，仅用于 httpStream（在 stdio 下绝不会启用）。

HTTP 传输

对于长期运行／联网部署：

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... TRANSPORT_TYPE=httpStream PORT=3000 npx -y oura-ring-mcp-server

MCP 端点位于 /mcp；somamcp 还提供公开的 GET /health 探测接口。

oura_data 工具

参数	适用范围	说明
collection	全部	要获取的数据集合（见下文）。
start_date / end_date	每日集合	YYYY-MM-DD。省略时 → 最近 7 天。
start_datetime / end_datetime	heartrate、ring_battery_level	ISO-8601。省略时 → 最近 24 小时。
latest	heartrate、ring_battery_level	仅返回最新样本。
document_id	带有详情路由的集合	按 ID 获取单条记录。
next_token	列表集合	上一响应中的分页游标。
fields	列表集合	以逗号分隔的稀疏字段集。

Collections

每日（start_date/end_date）：daily_activity、daily_sleep、daily_readiness、 daily_spo2、daily_stress、daily_resilience、daily_cardiovascular_age、vO2_max、 sleep、sleep_time、session、workout、tag、enhanced_tag、rest_mode_period

时间序列（start_datetime/end_datetime）：heartrate、ring_battery_level

列表 / 单例：ring_configuration、personal_info

示例提示词

• “我上周的平均准备度评分是多少？”
• “显示我在 2026-06-20 晚上的睡眠阶段。”
• “获取我最近一次心率读数。”
• “我本月记录了多少次锻炼？每次持续了多久？”

开发

pnpm install
pnpm validate   # format + lint + typecheck + test + build
pnpm dev        # watch build
pnpm inspect    # run against the MCP Inspector

无需佩戴戒指，设置 OURA_SANDBOX=true 即可访问 Oura 的演示数据集。

许可证

MIT