内容
# Oura Ring MCP 服务器
[](https://github.com/jordanburke/oura-ring-mcp-server/actions/workflows/node.js.yml)
[](https://www.npmjs.com/package/oura-ring-mcp-server)
[](https://opensource.org/licenses/MIT)
一个适用于 [Oura Ring API v2](https://cloud.ouraring.com/v2/docs) 的 [模型上下文协议](https://modelcontextprotocol.io) 服务器。将 Claude（或任何 MCP 客户端）指向您的 Oura 数据，并询问有关您的睡眠、准备度、活动、心率、锻炼等信息。
使用 [`somamcp`](https://github.com/sapientsai/SomaMCP)（遥测 + 反思）、[`functype`](https://functype.org)（类型化错误处理）和 `zod` 构建。
## 设计
该服务器不是为每个端点提供一个工具，而是公开一个**单独的综合 `oura_data` 工具**，并带有 `collection` 参数。这样可以保持工具模式的小（低令牌成本），同时涵盖每个 Oura `usercollection` 端点。该工具验证传递的参数对于选择的集合是否合法，并在不合法时返回可行的消息。
## 要求
- **Node.js 24+**（在 `.nvmrc` 中固定）
- Oura **个人访问令牌** - 在 [cloud.ouraring.com/personal-access-tokens](https://cloud.ouraring.com/personal-access-tokens) 上创建
## 用法
### Claude 桌面版 / Claude 代码
将以下内容添加到您的 MCP 客户端配置中（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"oura": {
"command": "npx",
"args": ["-y", "oura-ring-mcp-server"],
"env": {
"OURA_API_KEY": "您的个人访问令牌"
}
}
}
}
```
这会在标准输入/输出上运行服务器，这是大多数 MCP 客户端所期望的。
### 配置
| 环境变量 | 是否必需 | 默认值 | 描述 |
| ------------------------ | -------- | --------- | --------------------------------------------------------------------------- |
| `OURA_API_KEY` | 是 | — | Oura 个人访问令牌，作为 Bearer 令牌发送。 |
| `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 传输
用于长期运行/联网部署：
```bash
OURA_API_KEY=... 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` | 列表集合 | 以逗号分隔的稀疏字段集。 |
### 集合
**每日**（`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 晚上的睡眠阶段。"
- "获取我最近的心率读数。"
- "这个月我记录了多少次锻炼，时长是多少？"
## 开发
```bash
pnpm install
pnpm validate # 格式化 + 校验 + 类型检查 + 测试 + 构建
pnpm dev # 监视构建
pnpm inspect # 运行 MCP 检查器
```
尝试使用 `OURA_SANDBOX=true` 设置来访问 Oura 的演示数据集，而无需使用戒指。
## 许可证
MIT
