STARWARCLOUD STARWAR.AI
返回市场
欧拉-MCP-服务器

欧拉-MCP-服务器

作者：meimakes5 星标更新：2025-11-13
安装使用来源：spider==github.com

项目介绍

Oura MCP Server

UPSTRM

MCP (模型上下文协议)服务器，使AI助手能够通过OAuth2认证的API调用访问您的Oura Ring健康数据。

专为与Poke和其他兼容MCP的客户端无缝集成而设计。部署到Railway用于生产环境或本地运行进行开发。

在Railway上部署

特性

  • OAuth2带PKCE - 自动刷新令牌的安全身份验证
  • 9个MCP工具 - 访问睡眠、准备度、活动、心率、锻炼等
  • 双传输支持 - 同时支持SSE和可流式传输HTTP传输
  • 令牌加密 - 使用AES-256-GCM加密静态存储的OAuth令牌
  • 智能缓存 - 通过智能数据缓存减少API调用
  • 速率限制 - 内置防止API配额耗尽的保护
  • ngrok支持 - 便于移动和云集成的远程访问

先决条件

  • Node.js 18或更高版本
  • Oura Ring（支持所有世代 - 第二代、第三代和第四代）
  • 拥有API访问权限的Oura账户
  • Railway账户（推荐用于生产部署）或ngrok（用于本地开发）

安装

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

# 生成TOKEN_ENCRYPTION_KEY
openssl rand -hex 32

快速开始 - Railway部署（推荐）

步骤1：部署到Railway

  1. 单击下方按钮以部署到Railway：

在Railway上部署

或者手动操作：

  • 转到Railway
  • 从GitHub仓库创建新项目
  • 连接您分叉的此仓库
  1. 在本地生成所需密钥：
# 生成AUTH_TOKEN
openssl rand -hex 32

# 生成TOKEN_ENCRYPTION_KEY
openssl rand -hex 32

  1. 在Railway仪表板中添加环境变量：

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

  2. 等待部署完成并记录您的Railway 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凭证

在Railway仪表板中添加这些环境变量：

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

Railway将自动重新部署新的配置。

本地开发设置

步骤1：设置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服务器身份验证
AUTH_TOKEN=<生成的令牌>

# Oura OAuth凭证
OURA_CLIENT_ID=<您的客户端ID>
OURA_CLIENT_SECRET=<您的客户端密钥>
OURA_REDIRECT_URI=https://your-domain.ngrok.dev/oauth/callback

# 服务器配置
PORT=3001
NODE_ENV=development

# 令牌加密
TOKEN_ENCRYPTION_KEY=<生成的密钥>

# CORS来源
CORS_ORIGIN=*

# 日志记录（可选）
LOG_LEVEL=info  # 选项：error, warn, info, debug

使用方法

启动服务器

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

对于带有自动重载的开发：

npm run dev

连接到您的Oura账户

  1. 打开浏览器访问服务器的/oauth/authorize端点：
    • Railway：https://your-app.up.railway.app/oauth/authorize
    • ngrok：https://your-domain.ngrok.dev/oauth/authorize
    • 本地：http://localhost:3001/oauth/authorize
  2. 登录您的Oura账户
  3. 批准请求的权限
  4. 您将被重定向回带有成功消息的页面

连接到MCP客户端

Poke

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

该服务器同时支持SSE和可流式传输HTTP传输，以实现最大兼容性。

其他MCP客户端

配置您的MCP客户端：

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

可用的MCP工具

1. get_personal_info

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

2. get_sleep_summary

获取指定日期范围内的睡眠数据。

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD
  • include_hrv（可选）：布尔值

3. get_readiness_score

获取每日准备度评分。

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD

4. get_activity_summary

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

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD

5. get_heart_rate

获取每五分钟间隔的心率数据。

参数：

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

6. get_workouts

获取锻炼会话。

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD

7. get_sleep_detailed

获取详细的睡眠周期数据，包括心率和HRV。

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD

8. get_tags

获取用户创建的标签和笔记。

参数：

  • start_date（必需）：YYYY-MM-DD
  • end_date（可选）：YYYY-MM-DD

9. get_health_insights

基于最近数据获取AI驱动的洞察。

参数：

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

API端点

健康检查

GET /health

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

OAuth端点

GET  /oauth/authorize     - 开始OAuth流程
GET  /oauth/callback      - OAuth回调（自动）
GET  /oauth/status        - 获取连接状态（需要身份验证）
POST /oauth/disconnect    - 断开连接并清除令牌（需要身份验证）

MCP端点

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

可流式传输HTTP（推荐用于Poke）：

POST /sse                 - JSON-RPC请求，直接响应

经典SSE：

GET  /sse                 - 建立SSE连接
POST /message             - 通过会话发送JSON-RPC请求

安全性

令牌加密

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

身份验证

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

Authorization: Bearer YOUR_AUTH_TOKEN

速率限制

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

CORS

在.env中通过CORS_ORIGIN配置允许的来源。

日志记录

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

  • error - 仅关键错误（建议用于生产）
  • warn - 警告和错误
  • info - 关键操作、警告和错误（默认）
  • debug - 包括请求/响应正文在内的全部详细信息

通过LOG_LEVEL环境变量配置：

LOG_LEVEL=info  # 默认 - 平衡日志
LOG_LEVEL=error # 生产 - 最小输出
LOG_LEVEL=debug # 开发 - 详细调试

每个级别记录的内容：

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

故障排除

OAuth回调失败

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

令牌刷新失败

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

超出速率限制

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

Railway特定问题

服务器无法启动：

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

OAuth重定向失败：

  • 验证OURA_REDIRECT_URI使用了您的Railway域
  • 检查Railway部署是否为公共（非仅限私有网络）
  • 确保重定向URI使用HTTPS（Railway自动提供）

令牌未持久化：

  • Railway默认为tokens.json提供持久存储
  • 检查应用程序日志中的文件写入错误
  • 验证磁盘使用量未超过限制

本地开发问题

ngrok连接问题：

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

开发

项目结构

oura-mcp-server/
├── src/
│   ├── index.ts              # 主服务器文件
│   ├── oauth/
│   │   ├── handler.ts        # OAuth流程处理器
│   │   └── tokens.ts         # 令牌管理
│   ├── mcp/
│   │   ├── server.ts         # MCP协议实现
│   │   └── tools.ts          # 工具定义
│   ├── oura/
│   │   ├── client.ts         # Oura API客户端
│   │   └── types.ts          # TypeScript类型
│   ├── utils/
│   │   ├── encryption.ts     # 令牌加密
│   │   ├── cache.ts          # 数据缓存
│   │   └── validation.ts     # 输入验证
│   └── middleware/
│       ├── auth.ts           # 身份验证中间件
│       └── errorHandler.ts   # 错误处理
├── .env                      # 环境变量（git忽略）
├── tokens.json               # 加密的令牌（git忽略）
├── package.json
├── tsconfig.json
└── README.md

运行测试

npm test

类型检查

npm run typecheck

代码检查

npm run lint

部署选项

选项1：Railway（推荐）

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

选项2：本地开发

  • 成本：免费（ngrok免费层级）
  • 设置时间：约10分钟
  • 优点：
    • 完整的数据隐私（令牌留在本地）
    • 无托管费用
    • 对环境的完全控制
  • 限制：
    • 需要计算机运行
    • ngrok URL在重启时变化（免费层级）
  • 适合：开发、测试、个人使用

选项3：云VM（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等）

许可

MIT

支持

对于问题或疑问：

贡献

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