Oura Ring MCP Python

Oura MCP服务器（Python）

用于通过OAuth2身份验证访问Oura Ring健康数据的模型上下文协议（MCP）服务器的Python实现。

特性

• OAuth2身份验证 -通过自动令牌刷新进行安全身份验证
• 9 MCP工具 -获取睡眠、准备、活动、心率、锻炼等信息
• 令牌加密 -静态OAuth令牌的AES-256加密
• 健康洞察 -综合健康趋势分析
• 纯 Python -采用FastMCP和Starlette构建

先决条件

• Python 3.11或更高版本
• 拥有活跃Oura帐户的Oura戒指
• Oura API访问（OAuth应用程序）

安装

选项1：从源代码安装

# Clone or download this repository
cd oura-mcp-python

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

选项2：使用uv安装（更快）

cd oura-mcp-python
uv pip install -e .

配置

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

1. 首选 Oura OAuth应用程序
2. 使用您的Oura帐户登录
3. 点击 “新应用程序”
4. 填写：

- 应用程序名称： Personal MCP Server - 重定向URI: http://localhost:8000/oauth/callback - 范围： 选择所有可用范围

1. 保存并复制您的 客户端ID 和 客户端密钥

步骤2：创建环境文件

cp .env.example .env   # copy the template
# then edit .env with your credentials

注： .env 被忽视； .env.example 是已提交的模板。

步骤3：生成加密密钥

# Run this in Python to generate TOKEN_ENCRYPTION_KEY
import secrets
print("TOKEN_ENCRYPTION_KEY:", secrets.token_hex(32))

步骤4：配置.env

编辑您的 .env 文件：

# Oura OAuth Credentials
OURA_CLIENT_ID=your_client_id_here
OURA_CLIENT_SECRET=your_client_secret_here
OURA_REDIRECT_URI=http://localhost:8000/oauth/callback

# Token Encryption
TOKEN_ENCRYPTION_KEY=

# Server Configuration (optional; defaults shown)
HOST=0.0.0.0
PORT=8000

运行服务器

启动服务器

# Using the installed command
oura-mcp

# Or directly with Python
python -m oura_mcp.server

# Or with uvicorn for development
uvicorn oura_mcp.server:create_app --factory --reload --port 8000

连接您的Oura帐户

1. 打开浏览器： http://localhost:8000/oauth/authorize
2. 登录您的Oura帐户
3. 批准请求的权限
4. 连接后，您将看到一条成功消息

验证连接

检查运行状况端点：

curl http://localhost:8000/health

预期响应：

{
  "status": "healthy",
  "oauth_connected": true,
  "server": "Oura MCP Server (Python)",
  "version": "1.0.0"
}

连接到克劳德桌面

将此添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"],
      "env": {
        "API_KEY": "YOUR_AUTH_TOKEN_HERE"
      }
    }
  }
}

替代方案：直接stdio连接 （如果在本地运行）

{
  "mcpServers": {
    "oura": {
      "command": "python",
      "args": ["-m", "oura_mcp.server"],
      "cwd": "/path/to/oura-mcp-python",
      "env": {
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret",
        "OURA_REDIRECT_URI": "http://localhost:8000/oauth/callback"
      }
    }
  }
}

保存后重新启动Claude Desktop。

可用的MCP工具

1.获取个人信息

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

2.get_sleep_summary

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

参数：

• start_date （必填）：年月日
• end_date （可选）：YYYY-MM-DD
• include_detailed （可选）：包括详细的睡眠期数据

3.获取就绪内核

获取每日准备得分。

参数：

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

4.获取活动摘要

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

参数：

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

5.获取心率

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

参数：

• start_datetime （必填）：ISO 8601格式（例如2024-01-01T00:00:00）
• end_datetime （可选）：ISO 8601格式

6.锻炼

进行锻炼。

参数：

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

7.标签

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

参数：

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

8.get_sessions

获取引导和非引导会话数据。

参数：

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

9.获取健康信息

根据最新数据获取汇总的健康见解。

参数：

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

10.获取连接状态

检查Oura帐户是否已连接，令牌是否有效。

API终点

健康检查

GET /health

OAuth端点

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

MCP端点

POST /mcp                 - MCP JSON-RPC endpoint (Streamable HTTP)

部署选项

方案1：地方发展

在您的机器上运行，服务器可在本地主机上访问。

选项2：铁路/云部署

1. 推送到Git存储库
2. 部署到铁路、渲染或类似对象
3. 更新 OURA_REDIRECT_URI 到您部署的URL
4. 更新Oura OAuth应用程序的重定向URI

选项3:Docker

FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install -e .

EXPOSE 8000
CMD ["oura-mcp"]

docker build -t oura-mcp-python .
docker run -p 8000:8000 --env-file .env oura-mcp-python

故障排除

“未通过身份验证”错误

• 访问 /oauth/authorize 连接您的Oura帐户
• 检查您的OAuth凭据是否正确 .env

令牌刷新失败

• 确保 TOKEN_ENCRYPTION_KEY 没有改变
• 尝试断开连接(POST /oauth/disconnect)并重新连接

Oura的“无效重定向URI”

• 确保您的 OURA_REDIRECT_URI 与Oura OAuth应用程序中配置的完全匹配
• 包含完整路径： http://localhost:8000/oauth/callback

Claude Desktop看不到工具

• 验证服务器是否正在运行： curl http://localhost:8000/health
• 检查克劳德桌面日志：帮助→ 打开日志文件夹
• 确保 mcp-remote 可用： npx -y mcp-remote --help

发展

运行测试

pip install -e ".[dev]"
pytest

代码格式化

ruff format .
ruff check --fix .

许可证

麻省理工学院

学分

• 基于 meimakes/oura mcp服务器 TypeScript实现
• 建于 MCP Python SDK
• 使用 Oura API V2