oura-ring-python-mcp

An MCP server that gives Claude (or any MCP client) read-only access to your Oura Ring data: sleep, readiness, activity, stress, SpO2, resilience, workouts, sessions and heart rate. It talks to the Oura API v2 with its own small async client (oura_ring_mcp.core).

Tools

Daily tools take optional start_date and end_date (YYYY-MM-DD, both inclusive). Without them they cover the 7 days ending today; ranges are limited to 90 days. Each result echoes the range it covers, so the model always knows what "today" meant.

get_heart_rate takes optional start_datetime and end_datetime (ISO 8601). Without them it covers the last 24 hours; windows are limited to 7 days.

Per-interval series (5-minute activity classes, MET, sleep phases, in-sleep heart rate and HRV curves) are left out of results to keep them small; the scores, totals and averages are kept.

Setup

For a step-by-step guide, including creating the Oura application and troubleshooting, see the installation guide. Full documentation is at https://oura-ring-python-mcp.readthedocs.io.

The server signs in with OAuth2, since Oura has deprecated personal access tokens. You need an Oura API application (a client ID and secret) whose redirect URIs include http://localhost:47651/callback, with the scopes email, personal, daily, heartrate, workout, session, spo2 and stress allowed (resilience needs stress). Gen3 and Oura Ring 4 users need an active Oura membership for the API to return data.

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

Sign in once. This opens the browser, catches Oura's redirect on localhost, and saves the tokens to ~/.config/oura-ring-mcp/tokens.json (readable only by you):

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

From then on the server refreshes the access token by itself (Oura issues them for 30 days) and saves each new single-use refresh token. Run auth again only if you revoke access or the saved refresh token is lost.

If the redirect URI isn't http://localhost:<port>/... (or you're signing in over SSH or in Docker), auth asks you to paste the URL the browser ended up on instead; force that with auth --paste.

Run from PyPI

No clone needed; uv fetches and runs the published package:

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

In a client config, use "command": "uvx", "args": ["oura-ring-python-mcp"].

Run with Docker

Sign in on the host first (above), then mount the token folder so the container can read the tokens and save refreshed ones. The server speaks MCP over stdio, so keep -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

The image reads the tokens from /tokens/tokens.json. --user lets the container read and update your token file on Linux; Docker Desktop on macOS and Windows doesn't need it. To sign in from the container instead, run it with -it and the command auth --paste.

In a client config, use "command": "docker" with those arguments, and pass the variables through the client's env block.

Claude Desktop

Add to 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 tracing (optional)

Each tool call becomes a Langfuse trace, with a child span for each Oura API call. Install the extra and set the keys:

uv sync --extra langfuse

In the server command, use run --extra langfuse oura-ring-python-mcp instead of run oura-ring-python-mcp.

Privacy: sleep, heart rate and activity data are health data. By default, traces hold only tool names, timings and error class names. Setting LANGFUSE_CAPTURE_DATA=true sends your data to your Langfuse instance; only do that with an instance you trust, such as a self-hosted one.

Development

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

Releasing

Bump version in pyproject.toml and both versions in server.json (a test checks they match), commit, then push a tag:

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

The tag publishes to PyPI (pypi.yml, needs the PYPI_API_TOKEN secret), to ghcr.io/osjayaprakash/oura-ring-python-mcp (docker.yml), and then to the MCP Registry (mcp-registry.yml).

License

MIT