Oura MCP server

Oura MCP server

Read your Oura ring from Claude.ai and Claude Code: sleep with the full periods behind the score, readiness, activity, workouts, heart rate, stress, SpO2, resilience, cardiovascular age, VO2 max, bedtime recommendations, tags and rest mode. It talks to the documented Oura API v2 and puts an OAuth 2.1 login in front so you can add it to Claude.ai as a custom connector. Claude Code can use a plain token instead.

Why not the npm package

This started as a wrapper around @daveremy/oura-mcp and replaced it, because that package returns nothing for most of what you would ask it. It queries single-day ranges as start_date == end_date, and the Oura API does not answer those the way the naming suggests:

• sleep filters on bedtime_start in UTC, so a night that begins at 00:31 local (UTC+3) lands on the previous UTC day and falls outside its own day's window

• daily_activity and workout treat end_date as exclusive, making a same-day range zero-width

The result is silent: oura_sleep returns a score with an empty periods array, oura_activity returns null, and oura_workouts returns [], on every single-day call. Nothing errors, so it reads as "no data recorded" rather than "the query was wrong". This server pads the range on both sides and filters back by each record's own day field, which is timezone-correct, and follows next_token to exhaustion instead of silently returning one page.

Tools

Every date-scoped tool takes an optional date as YYYY-MM-DD and defaults to today. Oura files a night under the day you woke up.

oura_vo2_max, oura_sleep_time and oura_cardiovascular_age are sparse by design: Oura computes them periodically rather than daily, so an empty result is normal and not a sync failure.

How it fits together

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8441
        |
   auth-server.js  :8442    handles the login and the tokens
        |
   oura-mcp  :8440          streamable HTTP, local only
        |
   api.ouraring.com

Ports are 8440-8442 so they sit clear of the other MCPs on this host. The server on :8440 has no login of its own and refuses to bind anywhere but loopback, so it is only ever reached through the login layer.

Setup

Needs Python 3.12 or newer, and Node for the login layer.

python3 -m venv .venv
.venv/bin/pip install -e .
npm install --omit=dev

mkdir -p ~/.config/oura-mcp && chmod 700 ~/.config/oura-mcp
echo "OURA_TOKEN=your-personal-access-token" > ~/.config/oura-mcp/env
chmod 600 ~/.config/oura-mcp/env

CONFIG_DIR=~/.config/oura-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/oura-mcp/token
chmod 600 ~/.config/oura-mcp/token

Get the Oura token from cloud.ouraring.com.

Then fill in YOUR_USER and the hostname in systemd/*.service and nginx/oura-mcp.conf, and:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now oura-mcp oura-mcp-auth
sudo cp nginx/oura-mcp.conf /etc/nginx/sites-enabled/oura-mcp
sudo nginx -t && sudo systemctl reload nginx

Point a tunnel or an HTTPS proxy at 127.0.0.1:8441. OAuth needs HTTPS.

Check it from outside: discovery should return metadata, and /mcp without a token must return 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Connecting

Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.

Claude Code:

claude mcp add --transport http oura https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/oura-mcp/token)" --scope user

Running it over stdio instead, without any of the login layer:

OURA_TOKEN=your-token .venv/bin/oura-mcp

Credits

The login layer comes from rollecode/obsidian-remote-mcp.