Oura Ring

oura-ring-python-mcp

一个 MCP 服务，为 Claude（或任何 MCP 客户端）提供对 Oura Ring 数据的只读访问权限：睡眠、准备度、活动、压力、SpO2、韧性、锻炼、训练课程和心率。它通过自己的轻量级异步客户端（oura_ring_mcp.core）调用 Oura API v2。

工具

工具	返回内容
get_personal_info	年龄、体重、身高、生理性别、电子邮件
get_daily_sleep	每日睡眠评分及其影响因素
get_sleep_periods	每晚睡眠和小睡：阶段、效率、心率、HRV
get_daily_readiness	每日准备度评分、影响因素、温度偏差
get_daily_activity	每日活动评分、步数、卡路里、各活动强度等级的时长
get_daily_stress	每日处于高压力状态和恢复状态的时长
get_daily_spo2	每晚平均 SpO2 和呼吸干扰指数
get_daily_resilience	每日韧性等级及其影响因素
get_workouts	锻炼的类型、强度、卡路里、距离
get_sessions	冥想、呼吸和休息课程
get_heart_rate	心率采样值，包括最小值、最大值和平均 bpm

每日工具接受可选的 start_date 和 end_date（YYYY-MM-DD，包含起止日期）。未指定时，查询范围为截至今天的 7 天；日期范围最长为 90 天。每条结果都会注明所覆盖的日期范围，因此模型始终知道“今天”指什么。

get_heart_rate 接受可选的 start_datetime 和 end_datetime（ISO 8601）。未指定时，查询范围为最近 24 小时；时间窗口最长为 7 天。

为缩小结果体积，不包含按时间间隔划分的序列数据（5 分钟活动类别、MET、睡眠阶段、睡眠期间的心率和 HRV 曲线）；但会保留评分、总量和平均值。

设置

如需分步指南（包括创建 Oura 应用和排查问题），请参阅安装指南。 完整文档请访问 https://oura-ring-python-mcp.readthedocs.io。

由于 Oura 已弃用个人访问令牌，服务端使用 OAuth2 登录。你需要一个 Oura API 应用（包含客户端 ID 和密钥），其重定向 URI 必须包含 http://localhost:47651/callback，并允许使用以下作用域：email、personal、daily、 heartrate、workout、session、spo2 和 stress（resilience 需要 stress）。Gen3 和 Oura Ring 4 用户需要有效的 Oura 会员资格，API 才会返回数据。

git clone https://github.com/osjayaprakash/oura-ring-python-mcp.git && cd oura-ring-python-mcp
uv sync

登录一次。此操作会打开浏览器，在 localhost 上捕获 Oura 的重定向，并将令牌保存到 ~/.config/oura-ring-mcp/tokens.json（仅你本人可读取）：

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uv run oura-ring-python-mcp auth

之后，服务端会自动刷新访问令牌（Oura 签发的令牌有效期为 30 天）， 并保存每个新的单次使用刷新令牌。只有在撤销访问权限或已保存的刷新令牌丢失时，才需要再次运行 auth。

变量	必填	默认值	含义
OURA_CLIENT_ID	是		Oura API 应用的客户端 ID
OURA_CLIENT_SECRET	是		Oura API 应用的客户端密钥
OURA_TOKEN_FILE	否	~/.config/oura-ring-mcp/tokens.json（如果已设置，则位于 $XDG_CONFIG_HOME 下）	auth 保存令牌以及服务端读取令牌的位置
OURA_TIMEZONE	否	机器的时区	你的 IANA 时区，例如 Europe/London，以便“今天”与 Oura 的日期一致。在 Docker 中运行时请设置此项，因为默认值为 UTC
OURA_REDIRECT_URI	否	http://localhost:47651/callback	必须与应用中的某个重定向 URI 完全一致
OURA_SCOPES	否	email personal daily heartrate workout session spo2 stress	要请求的作用域

如果重定向 URI 不是 http://localhost:<port>/...（或者你通过 SSH 登录或在 Docker 中运行），auth 会要求你粘贴浏览器最终打开的 URL；使用 auth --paste 可强制启用此方式。

从 PyPI 运行

无需克隆；uv 会获取并运行已发布的软件包：

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uvx oura-ring-python-mcp auth   # once
uvx oura-ring-python-mcp

在客户端配置中，使用 "command": "uvx", "args": ["oura-ring-python-mcp"]。

使用 Docker 运行

先在主机上登录（如上所述），然后挂载令牌文件夹，以便容器读取令牌并保存刷新后的令牌。服务端通过 stdio 使用 MCP 通信，因此请保留 -i：

docker run -i --rm --user "$(id -u):$(id -g)" \
  -e OURA_CLIENT_ID -e OURA_CLIENT_SECRET -e OURA_TIMEZONE=Europe/London \
  -v ~/.config/oura-ring-mcp:/tokens \
  ghcr.io/osjayaprakash/oura-ring-python-mcp:latest

镜像从 /tokens/tokens.json 读取令牌。在 Linux 上，--user 可让容器读取并更新你的令牌文件；macOS 和 Windows 上的 Docker Desktop 无需此选项。 若要改为从容器中登录，请使用 -it 运行容器，并执行命令 auth --paste。

在客户端配置中，使用 "command": "docker" 并传入相应参数，同时通过客户端的 env 块传递变量。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "oura": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/oura-ring-python-mcp", "run", "oura-ring-python-mcp"],
      "env": {
        "OURA_CLIENT_ID": "your-client-id",
        "OURA_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

claude mcp add oura \
  -e OURA_CLIENT_ID=your-client-id \
  -e OURA_CLIENT_SECRET=your-client-secret \
  -- uv --directory /absolute/path/to/oura-ring-python-mcp run oura-ring-python-mcp

Langfuse 跟踪（可选）

每次工具调用都会生成一个 Langfuse 跟踪，每次 Oura API 调用都会生成一个子跨度。 安装附加项并设置密钥：

uv sync --extra langfuse

在服务端命令中，使用 run --extra langfuse oura-ring-python-mcp，而不是 run oura-ring-python-mcp。

变量	含义
LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY	仅当两者都已设置时才启用跟踪
LANGFUSE_BASE_URL	用于可自托管或区域实例的 Langfuse URL（默认：Langfuse Cloud）
LANGFUSE_CAPTURE_DATA	设为 true 可包含工具输入、输出和错误消息。默认值为 false

**隐私：**睡眠、心率和活动数据属于健康数据。默认情况下，跟踪仅保存工具名称、耗时和错误类别名称。设置 LANGFUSE_CAPTURE_DATA=true 会将你的数据发送到 Langfuse 实例；仅在信任该实例时才这样做，例如使用可自托管的实例。

开发

uv sync
uv run pytest            # offline suite
uv run pytest -m live    # hits the real API; needs `auth` first
uv run ruff check src tests && uv run ruff format --check src tests

发布

更新 pyproject.toml 中的 version 以及 server.json 中的两个版本号（测试会检查它们是否一致），提交更改，然后推送标签：

git tag v0.1.0 && git push origin v0.1.0

该标签会将项目发布到 PyPI（pypi.yml，需要 PYPI_API_TOKEN 密钥）、ghcr.io/osjayaprakash/oura-ring-python-mcp（docker.yml），然后发布到 MCP Registry（mcp-registry.yml）。

许可证

MIT