AI导哈

健康数据协议服务器

Oura MCP服务器是一个通过OAuth2认证API调用使AI助手访问Oura Ring健康数据的模型上下文协议服务器，适用于健康数据分析和集成开发。

  • by madebydia
  • TypeScript
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 meimakes/oura-mcp-server

使用说明

Oura MCP服务器

MCP（模型上下文协议）服务器，使人工智能助手能够通过OAuth2-身份验证的API调用访问您的Oura Ring健康数据。

建造于 @madebydia

专为无缝集成而设计 戳 以及其他MCP兼容客户端。部署到Railway进行生产使用，或在本地运行进行开发。

特性

  • OAuth2与PKCE -通过自动令牌刷新进行安全身份验证
  • 9 MCP工具 -获取睡眠、准备、活动、心率、锻炼等信息
  • 双重运输支持 -SSE和流式HTTP传输
  • 令牌加密 -静态OAuth令牌的AES-256-GCM加密
  • 智能缓存 -使用智能数据缓存减少API调用
  • 速率限制 -针对API配额耗尽的内置保护
  • ngrok支持 -轻松远程访问移动和云集成

先决条件

  • Node.js 18或更高版本
  • Oura Ring（支持所有世代-第2代、第3代和第4代）
  • 拥有API访问权限的Oura帐户
  • 铁路账户（建议用于生产部署）或ngrok（用于当地发展）

安装

  1. 克隆存储库：
git clone https://github.com/madebydia/oura-mcp-server.git
cd oura-mcp-server
  1. 安装依赖项：
npm install
  1. 复制示例环境文件：
cp .env.example .env
  1. 生成所需的机密：
# Generate AUTH_TOKEN
openssl rand -hex 32

# Generate TOKEN_ENCRYPTION_KEY
openssl rand -hex 32

快速入门-铁路部署（推荐）

步骤1：部署到铁路

  1. 单击下面的按钮部署到铁路：

或手动：

  • 首选 铁路
  • 从GitHub仓库创建新项目
  • 连接此存储库的分支
  1. 在本地生成所需的机密：
# Generate AUTH_TOKEN
openssl rand -hex 32

# Generate TOKEN_ENCRYPTION_KEY
openssl rand -hex 32

  1. 在铁路仪表板中，添加环境变量：

    • AUTH_TOKEN -您生成的身份验证令牌
    • TOKEN_ENCRYPTION_KEY -您生成的加密密钥
    • NODE_ENV -设置为 production
    • CORS_ORIGIN -设置为 * 或您的特定域名
    • PORT -未设置（铁路将自动分配）

  2. 等待部署完成，并记下您的铁路URL（例如。， https://your-app.up.railway.app)

步骤2：注册Oura OAuth应用程序

  1. 首选https://cloud.ouraring.com/oauth/applications
  2. 点击“创建新应用程序”
  3. 填写：
    • 应用程序名称： “个人MCP服务器”（或您选择）
    • 重定向URI: https://your-app.up.railway.app/oauth/callback
    • 范围： 选择所有可用范围
  4. 保存 客户端ID 和 客户端密钥

步骤3：在Railway中配置OAuth凭据

在铁路仪表板中添加以下环境变量：

  • OURA_CLIENT_ID -您的Oura客户ID
  • OURA_CLIENT_SECRET -您的Oura客户秘密
  • OURA_REDIRECT_URI - https://your-app.up.railway.app/oauth/callback

铁路将自动重新部署新配置。

地方发展设置

第一步：设置ngrok

  1. 安装并验证ngrok：
ngrok config add-authtoken YOUR_NGROK_TOKEN
  1. 启动ngrok隧道：
ngrok http 3001
  1. 注意你的ngrok URL（例如。， https://your-domain.ngrok.dev)

步骤2：配置环境变量

复制 .env.example 到 .env 并配置：

# MCP Server Authentication
AUTH_TOKEN=<generated-token>

# Oura OAuth Credentials
OURA_CLIENT_ID=<your-client-id>
OURA_CLIENT_SECRET=<your-client-secret>
OURA_REDIRECT_URI=https://your-domain.ngrok.dev/oauth/callback

# Server Configuration
PORT=3001
NODE_ENV=development

# Token Encryption
TOKEN_ENCRYPTION_KEY=<generated-key>

# CORS Origin
CORS_ORIGIN=*

# Logging (optional)
LOG_LEVEL=info  # Options: error, warn, info, debug

用法

启动服务器

  1. 构建TypeScript代码：
npm run build
  1. 启动服务器：
npm start

对于自动重新加载的开发：

npm run dev

连接您的Oura帐户

  1. 打开服务器的浏览器 /oauth/authorize 端点：
    • 铁路： https://your-app.up.railway.app/oauth/authorize
    • 吸烟： https://your-domain.ngrok.dev/oauth/authorize
    • 当地： http://localhost:3001/oauth/authorize
  2. 登录您的Oura帐户
  3. 批准请求的权限
  4. 您将被重定向回一条成功消息

连接到MCP客户端

戳

  1. 打开Poke应用程序
  2. 前往设置→ 集成→ 添加集成
  3. 选择“模型上下文协议（MCP）”
  4. 输入：
    • 姓名： 奥拉
    • 服务器URL: https://your-app.up.railway.app/sse （或您的部署URL）
    • API密钥： 你的 AUTH_TOKEN 来自环境变量
  5. 点击“添加集成”

服务器支持SSE和Streamable HTTP传输，以实现最大兼容性。

对于铁路部署，请附加一个持久卷（例如 /data). 服务器自动将其加密的Oura OAuth令牌文件存储在 $RAILWAY_VOLUME_MOUNT_PATH/tokens.json，因此正常部署不需要 重新授权。 TOKEN_ENCRYPTION_KEY 在部署过程中必须保持稳定。

其他MCP客户端

使用以下配置您的MCP客户端：

  • 服务器URL: https://your-app.up.railway.app/sse （或您的部署URL）
  • API密钥（承载令牌）： 你的 AUTH_TOKEN 来自环境变量

可用的MCP工具

1.获取个人信息

获取用户的个人信息和戒指详细信息。

2.get_sleep_summary

获取某个日期范围的睡眠数据。

睡眠和阶段持续时间以秒为单位从Oura的详细睡眠中返回 期间记录。每日分数终点的贡献值已公开 仅作为分数；它们不被视为小时或持续时间。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD
  • include_hrv （可选）：布尔值

3.获取就绪内核

获取每日准备得分。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD

4.获取活动摘要

获取日期范围的活动数据。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD

5.获取心率

以5分钟为间隔获取心率数据。

参数：

  • start_datetime （必填）：ISO 8601格式
  • end_datetime （可选）：ISO 8601格式

6.锻炼

进行锻炼。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD

7.获取睡眠详细信息

获取心率和心率变异性的详细睡眠期数据。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD

8.标签

获取用户创建的标签和注释。

参数：

  • start_date （必填）：年月日
  • end_date （可选）：YYYY-MM-DD

9.获取健康信息

基于最新数据获取人工智能驱动的见解。

参数：

  • days （可选）：要分析的天数（默认值：7）

API终点

健康检查

GET /health

返回服务器状态、OAuth连接状态和缓存统计信息。

OAuth端点

GET  /oauth/authorize     - Start OAuth flow
GET  /oauth/callback      - OAuth callback (automatic)
GET  /oauth/status        - Get connection status (requires auth)
POST /oauth/disconnect    - Disconnect and clear tokens (requires auth)

MCP端点

服务器支持两种传输模式：

流式HTTP（推荐用于Poke）：

POST /sse                 - JSON-RPC requests with direct responses

经典SSE：

GET  /sse                 - Establish SSE connection
POST /message             - Send JSON-RPC requests via session

安全

令牌加密

所有OAuth令牌都使用AES-256-GCM加密进行静态加密。

认证

MCP端点需要承载令牌身份验证：

Authorization: Bearer YOUR_AUTH_TOKEN

速率限制

  • MCP端点：每个IP每15分钟100个请求
  • Oura API：每天5000个请求（自动跟踪）

跨域资源共享

在中配置允许的来源 .env 与 CORS_ORIGIN.

日志记录

服务器使用具有可配置日志级别的结构化日志记录：

  • error -仅严重错误（建议用于生产）
  • warn -警告和错误
  • info -关键操作、警告和错误（默认）
  • debug -详尽无遗，包括请求/响应机构

通过配置 LOG_LEVEL 环境变量：

LOG_LEVEL=info  # Default - balanced logging
LOG_LEVEL=error # Production - minimal output
LOG_LEVEL=debug # Development - verbose debugging

每个级别记录的内容：

  • 错误：身份验证失败、API错误、OAuth失败、速率限制
  • 警告：API密钥尝试无效，缺少SSE会话
  • 信息：SSE连接、工具执行、OAuth操作、MCP方法调用
  • 调试：完整的JSON-RPC请求/响应、连接生命周期事件

故障排除

OAuth回调失败

  • 验证Oura应用程序设置中的重定向URI是否完全匹配
  • 确保您的服务器可访问（铁路部署或本地运行的ngrok）
  • 检查 OURA_CLIENT_ID 和 OURA_CLIENT_SECRET 是正确的
  • 确认 OURA_REDIRECT_URI 匹配您的部署URL

令牌刷新失败

  • 验证 TOKEN_ENCRYPTION_KEY 设置正确，未更改
  • 检查 tokens.json 文件存在并且可读
  • 确保Oura帐户中的刷新令牌未被撤销
  • 对于铁路：检查是否启用了持久存储

超出费率限制

  • 缓存是内置的，默认TTL为5分钟
  • 降低MCP客户端的轮询频率
  • 检查API响应中的速率限制标头
  • 监控使用情况 /health 端点

铁路具体问题

服务器未启动：

  • 检查铁路日志是否有错误
  • 验证是否设置了所有必需的环境变量
  • 确保 PORT 变量未设置（铁路自动分配）
  • 检查构建日志中的TypeScript编译错误

OAuth重定向失败：

  • 验证 OURA_REDIRECT_URI 使用您的铁路域
  • 检查铁路部署是否是公共的（不仅仅是专用网络）
  • 确保重定向URI中使用HTTPS（Railway会自动提供此功能）

令牌不持久：

  • 默认情况下，Railway为以下对象提供持久存储 tokens.json
  • 检查应用程序日志中的文件写入错误
  • 验证磁盘使用率是否未超过限制

地方发展问题

ngrok连接问题：

  • 重启ngrok隧道
  • 更新 OURA_REDIRECT_URI 如果ngrok URL更改
  • 验证ngrok身份验证令牌是否有效
  • 检查ngrok是否未被防火墙阻止

发展

项目结构

oura-mcp-server/
├── src/
│   ├── index.ts              # Main server file
│   ├── oauth/
│   │   ├── handler.ts        # OAuth flow handler
│   │   └── tokens.ts         # Token management
│   ├── mcp/
│   │   ├── server.ts         # MCP protocol implementation
│   │   └── tools.ts          # Tool definitions
│   ├── oura/
│   │   ├── client.ts         # Oura API client
│   │   └── types.ts          # TypeScript types
│   ├── utils/
│   │   ├── encryption.ts     # Token encryption
│   │   ├── cache.ts          # Data caching
│   │   └── validation.ts     # Input validation
│   └── middleware/
│       ├── auth.ts           # Authentication middleware
│       └── errorHandler.ts   # Error handling
├── .env                      # Environment variables (gitignored)
├── tokens.json               # Encrypted tokens (gitignored)
├── package.json
├── tsconfig.json
└── README.md

运行测试

npm test

类型检查

npm run typecheck

代码检查

npm run lint

部署选项

方案1：铁路（推荐）

  • 成本： 免费套餐，随年龄增长付费
  • 设置时间： 约5分钟
  • 优点：
    • 始终可用（24/7正常运行时间）
    • 从GitHub自动部署
    • 内置HTTPS
    • 无需服务器管理
    • 令牌的持久存储
  • 最适合： 生产使用、移动访问、与他人共享

方案2：地方发展

  • 成本： 免费（ngrok免费套餐）
  • 设置时间： 约10分钟
  • 优点：
    • 完全的数据隐私（令牌保持本地）
    • 无托管费用
    • 完全控制环境
  • 限制：
    • 要求计算机正在运行
    • 重新启动时ngrok URL更改（免费层）
  • 最适合： 开发、测试、个人使用

选项3：云虚拟机（VPS）

  • 部署到DigitalOcean、AWS EC2、Google Cloud等。
  • 始终可用静态IP
  • 更多控制，但需要服务器管理

选项4:Docker

docker build -t oura-mcp-server .
docker run -p 3001:3001 --env-file .env oura-mcp-server

可以部署到任何兼容Docker的平台（Fly.io、Render等）

许可证

麻省理工学院

支持

对于问题或疑问：

  • GitHub问题：https://github.com/madebydia/oura-mcp-server/issues
  • 我们的API文件：https://cloud.ouraring.com/docs
  • MCP协议：https://modelcontextprotocol.io

贡献

欢迎投稿！请阅读 贡献.md 了解详情。

相关 MCP