MCP for Oura

mcpforoura

用日常语言向 AI 助手询问你的 Oura Ring 数据。 mcpforoura 是一个托管式、多租户的 Model Context Protocol 服务，适用于 Oura Ring，运行地址为 **https://mcp-oura.smirnov.link/mcp**。将其连接到 Claude（或任何兼容 MCP 的客户端），通过 Oura 授权一次，即可使用 21 个只读工具查询睡眠、准备度、活动、生物特征数据和长期趋势。多租户 OAuth：每位用户都通过自己的 Oura 账户进行身份验证。只读。基于 Cloudflare Workers 构建。

已列入 Smithery 和 官方 MCP Registry。

小规模连接器——目前受 Oura 开发模式的 10 位用户上限限制；生产环境申请尚待审批。与 Oura Health Oy 无关联。

状态： 已部署并运行。21 个工具已上线——涵盖核心睡眠、准备度和活动数据，以及生物特征数据、综合快照和分析。第 5 阶段的周期工具已移除，等待 Oura API 支持（见下文“不可用”）。完整构建历史见里程碑表。

你可以询问的内容

连接后，你的助手可以回答以下问题：

• “我昨晚睡得怎么样？” — 睡眠阶段、时间、HR 和 HRV
• “我这周的 HRV 对我来说正常吗？” — 与你的个人基线进行比较
• “我今天状态如何？” — 提供准备度、建议睡眠时间和昨天统计数据的晨间简报
• “饮酒会影响我的恢复吗？” — 将记录的标签与任何指标关联分析
• “标记出这个月对我来说异常的日子。” — 统计异常检测

这些问题对应 4 个阶段中的 21 个工具（已移除阶段 5 的周期工具——见下文“不可用”）：

核心（原始 M6）

工具	适用场景
get_daily_summary	“我的周六过得怎么样？”/“显示昨天的准备度。”单日睡眠、准备度和活动快照。
get_date_range	“我这周睡得怎么样？”/“显示我过去一个月的 HRV。”查询最多 180 天内的单项指标。
get_last_night_sleep	“我昨晚睡得怎么样？”最近一晚的评分、睡眠阶段细分、时间、HR/HRV。
ping	诊断工具。验证连接器已通过身份验证且可访问。
_internal_personal_info	诊断工具。验证 Oura 令牌有效且 API 正在响应。

阶段 1 — 活动与标签

工具	适用场景
get_workouts	列出日期范围内记录或自动检测到的锻炼（最多 180 天）。
get_sessions	列出正念课程（冥想、呼吸、放松）。
get_heart_rate_series	24 小时窗口内的日间 HR 时间序列，可按 5 分钟/15 分钟/原始数据分桶。
get_tags	用户记录的自定义标签（咖啡因、酒精、自定义备注）。
compare_to_baseline	“这对我来说正常吗？”将某日指标与 30 天和 90 天个人基线进行比较。

阶段 2 — A 级每日指标

工具	适用场景
get_stress	查询某日的每日高压力和恢复秒数。
get_spo2	夜间平均血氧（SpO2）和呼吸紊乱指数。
get_resilience	查询某日 Oura 的长期压力恢复能力评分。
get_cardio_age	根据 HRV、静息 HR 和其他信号得出的心血管年龄估值。
get_vo2_max	查询日期前 30 天内最近一次 VO2 最大值测量。
get_recommended_sleep_time	查询某日 Oura 建议的就寝时间范围。
get_rest_mode_periods	列出日期范围内因疾病或恢复而启用的休息模式时段。

阶段 3 — 综合工具

工具	适用场景
get_morning_briefing	“我今天状态如何？”结构化快照：准备度、建议睡眠时间和昨天的统计数据。
get_weekly_recap	1–28 天的时间范围，包含各项指标的均值/最小值/最大值。默认 7 天。

阶段 4 — 分析

工具	适用场景
find_anomalies	标记指标偏离滚动窗口均值超过 N σ 的日子。
correlate_tag_with_metric	“饮酒会影响我的 HRV 吗？”比较带标签日与不带标签日的指标统计数据。

不可用

周期分析（get_cycle_phase、get_cycle_history、compare_metric_across_cycle_phases）最初计划在阶段 5 中实现，但Oura 的公开 v2 API 不提供月经周期端点——周期洞察功能仅在 Oura 应用中提供。一位 Beta 用户遇到 404 错误后，这些工具便被移除；有关原因的详细记录，请查看 git 历史（feat/phase-5-cycle 和 feat/remove-cycle-tools 分支）。如果用户手动标记月经开始日，基于标签的记录功能可通过 get_tags 提供部分替代方案。

在 Claude 中添加连接器

1. 点击 Add to Claude。系统会在 claude.ai 上打开 Add custom connector 对话框，并填入名称（Oura）和 URL。检查这两个值，然后点击 Add。
2. 在此服务的授权页面上批准 → 重定向到 Oura → 在 Oura 上授权 → 返回 Claude。

要手动添加，请前往 Customize → Connectors → Add custom connector，并将 https://mcp-oura.smirnov.link/mcp 设为 URL。

使用 Team 或 Enterprise 计划时，所有者可为整个组织添加自定义连接器。所有者可以使用组织版链接。成员随后可通过 Customize → Connectors 使用自己的 Oura 账户进行连接。

此连接器目前最多支持 10 位已授权用户（Oura 默认的开发模式限制）。如需取消此限制，Oura 必须批准该 Oura 开发者应用进入生产环境。

架构

基于 Cloudflare Workers 的两阶段 OAuth：

• 流程 A（MCP 客户端 ↔ 此服务）。 由 @cloudflare/workers-oauth-provider 处理。采用标准 OAuth2 + PKCE + 动态客户端注册。授权页面在服务端渲染，并包含 CSRF 令牌。
• 流程 B（此服务 ↔ Oura）。 手动实现。在流程 A 中触发：重定向到 cloud.ouraring.com，将返回的代码交换为令牌，获取 /personal_info 以推导稳定的用户 ID，将令牌以 AES-GCM 加密后存储在 Cloudflare KV 中，然后附上该用户 ID 作为 props，完成流程 A。

一个派生自 McpAgent 的 Durable Object 会保存会话状态，并将 MCP 方法调用路由到类型化工具处理程序。每个工具都会在每次调用时创建一个 OuraClient，负责处理令牌刷新、区分 401 情况（需要重新授权、端点受限或账户成员资格未激活），以及 429 指数退避。

完整的逐文件讲解请参阅 CLAUDE.md。

设置（运维人员）

一次性操作：

1. Oura 开发者应用 — 前往 cloud.ouraring.com → API Applications → New。

   • 重定向 URI：https://<your-host>/oura/callback
   • 隐私政策 URL：https://<your-host>/privacy
   • 服务条款 URL：https://<your-host>/tos

2. Cloudflare KV 命名空间（将 ID 粘贴到 wrangler.jsonc 中）：

   npx wrangler kv namespace create mcpforoura-OAUTH_KV
   npx wrangler kv namespace create OURA_TOKENS
   npx wrangler kv namespace create OURA_CACHE
   

   在 OAUTH_KV 前加上 mcpforoura-，以避免与同一 CF 账户中也使用名为 OAUTH_KV 的绑定的其他 Worker 冲突。

3. 首次部署（注册 Worker，以便为其配置密钥）：

   npx wrangler deploy
   

4. 密钥：

   echo -n "$CLIENT_ID"     | npx wrangler secret put OURA_CLIENT_ID
   echo -n "$CLIENT_SECRET" | npx wrangler secret put OURA_CLIENT_SECRET
   openssl rand -base64 32  | tr -d '\n' | npx wrangler secret put ENCRYPTION_SECRET
   

   请妥善备份 ENCRYPTION_SECRET——如果它丢失，存储的令牌将无法解密，所有用户都必须重新授权。

5. 自定义域名 — 如果根域名区域位于同一个 Cloudflare 账户中，wrangler.jsonc 中的 routes 配置块（带有 custom_domain: true）会在下次部署时自动绑定子域名。否则，请在 Cloudflare 控制面板中手动配置。

可发现性

该服务会向 MCP 注册表聚合器发布以下元数据：

路径	用途
/.well-known/oauth-authorization-server	OAuth2 授权服务器元数据（由 @cloudflare/workers-oauth-provider 提供）。
/.well-known/oauth-protected-resource	OAuth2 受保护资源元数据（由 @cloudflare/workers-oauth-provider 提供）。
/.well-known/glama.json	Glama 目录发现 — https://glama.ai/mcp。
/.well-known/mcp/server-card.json	Smithery 扫描回退（仅在其自动扫描器无法通过 OAuth 获取工具列表时使用）。
server.json（仓库根目录）	官方 MCP 注册表提交文件 — 命名空间 link.smirnov/mcp-oura，通过 smirnov.link 完成 DNS 验证。使用 mcp-publisher 发布。

向官方 MCP 注册表提交服务（PulseMCP、mcp.so 和其他聚合器会从中获取信息）：

# One-time, from this repo root
go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest
mcp-publisher login dns smirnov.link   # prints a TXT record to add in Cloudflare DNS
mcp-publisher publish                  # uses server.json in the repo root

提交到 Smithery：在 smithery.ai/new 粘贴 https://mcp-oura.smirnov.link/mcp，并在扫描期间完成 OAuth 流程。

提交到 Glama：在 glama.ai/mcp/servers 使用“Add Server”（添加服务），他们会自动从 /.well-known/glama.json 获取维护者信息。

开发

cp .dev.vars.example .dev.vars      # fill in
npm install
npm run dev

本地开发会使用与生产环境相同的 Oura 重定向 URI，因此通常更适合通过 wrangler dev --remote 测试，这样授权流程就能通过已部署的基础设施完成。

隐私与数据处理

• Oura OAuth 令牌会在 Cloudflare Workers KV 中静态加密存储（AES-GCM，使用按用户派生的 HKDF 密钥）。
• Oura 戒指数据按需获取，并且（缓存层上线后）可能会短暂缓存在 KV 中，TTL 范围为 5 分钟（当天数据）至 24 小时（历史数据）。
• 不会记录戒指数据。
• 断开连接器会撤销 OAuth 授权；令牌将无法访问。
• 完整政策请参阅已部署网站上的 /privacy。

状态

已部署在 Smirnov Labs 的 Cloudflare 账户上，网址为 https://mcp-oura.smirnov.link。自定义域名通过 wrangler.jsonc 中的 routes 块映射。已配置三个 KV 命名空间（mcpforoura-OAUTH_KV、OURA_TOKENS、OURA_CACHE）。已设置三个密钥（OURA_CLIENT_ID、OURA_CLIENT_SECRET、ENCRYPTION_SECRET）。

构建进度

里程碑	状态
M1 — Worker 脚手架	✅
M2 — OAuth 提供方 + Hono 授权页面 + ping	✅
M3 — Oura OAuth 流程 B	✅
M4 — OuraClient（刷新、401 歧义处理、429 退避）	✅
M5 — AES-GCM 令牌加密	✅
M6 — 工具 1–3	✅
D1 — 首次部署到 mcp-oura.smirnov.link	✅
D2 — CLAUDE.md + 扩展版 README + LICENSE	✅
D3 — 推送到 GitHub 上的 Smirnov-Labs/mcpforoura	✅
M7 — 带日期感知 TTL 的 KV 响应缓存	✅
M8 — 工具 4–8（锻炼、会话、HR 序列、标签、基线）	✅
阶段 1–4 — 另外 16 个工具（Tier A、复合工具、分析）	✅
阶段 5 — 周期工具（已移除；Oura v2 API 没有公开的周期端点）	❌
M9 — Vitest 测试 + 部署文档完善	✅

许可证

MIT。请参阅 LICENSE。