Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
uvx my-oura-mcp==0.4.2Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
OURA_CLIENT_ID=<value> OURA_CLIENT_SECRET=<secret> OURA_REDIRECT_URI=<value> OURA_API_MODE=<value> OURA_TZ=<value> OURA_TOKEN_STORE=<value> OURA_PUBLIC_URL=<value> OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS=<value> claude mcp add io.github.antvsl-oura-mcp -- uvx my-oura-mcp==0.4.2Run in a terminal.
{ "mcpServers": { "io.github.antvsl-oura-mcp": { "command": "uvx", "args": [ "my-oura-mcp==0.4.2" ], "env": { "OURA_CLIENT_ID": "<value>", "OURA_CLIENT_SECRET": "<secret>", "OURA_REDIRECT_URI": "<value>", "OURA_API_MODE": "<value>", "OURA_TZ": "<value>", "OURA_TOKEN_STORE": "<value>", "OURA_PUBLIC_URL": "<value>", "OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS": "<value>" } } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
Gives Claude, ChatGPT, and Codex access to your Oura Ring data: sleep, readiness, HRV, resting heart rate, activity, SpO₂, stress.
Ask "how did I sleep last week" and your MCP client calls the right tool and gets a summary back — not a wall of JSON:
Sleep, readiness, HRV, resting heart rate, activity and stress from your Oura Ring
{
"metric": "sleep_detail",
"period": { "start": "2026-07-23", "end": "2026-07-29", "days": 7 },
"stats": {
"total_h": { "mean": 7.1, "min": 5.9, "max": 8.4 },
"deep_h": { "mean": 1.3, "min": 0.9, "max": 1.8 },
"avg_hrv": { "mean": 42, "min": 31, "max": 55, "trend_per_week": 1.8 },
"efficiency": { "mean": 88, "min": 82, "max": 93 }
}
}
New to MCP? Model Context Protocol lets AI clients reach external data. Install this server, connect it once, then ask about your sleep in plain language. No coding involved.
Works locally in Claude Code and Codex, and remotely in claude.ai and ChatGPT once it is deployed to a server of your own.
Читать по-русски: README.ru.md
raw=True away.
A month of heart-rate data shrinks by more than 10×.stdio for local use, streamable-http
for remote. A flag apart, not a rewrite.day field, and returns heart-rate
timestamps in UTC. Both quietly lose or misplace data outside UTC. This
server handles it — see Timezone handling.next_token pagination, retries
dropped connections with exponential backoff, and turns HTTP status codes
into messages that say what to fix.Requires uv. No Oura token needed for this part.
git clone https://github.com/AntVsl/oura_mcp && cd oura_mcp
cp .env.example .env
uv sync
Check that data flows (hits Oura's sandbox, no auth required):
uv run python -m my_oura_mcp.smoke
Connect it locally — the server prints the commands with the absolute path already filled in, and writes nothing itself:
uv run my-oura-mcp install
Then ask your client for an Oura summary. The get_status tool reports which
mode the server is in.
Every data tool takes either days_back or an explicit start_date/end_date
pair (YYYY-MM-DD), plus raw to get Oura's untouched response.
The sandbox returns synthetic data. For your own you need an Oura application and a one-time authorization — no review to pass, a fresh application works immediately.
When registering: Redirect URI is http://localhost:8765/callback, matched
byte for byte. Scopes are daily, heartrate, tag, spo2, stress,
heart_health. Everything else is arbitrary.
Tokens refresh themselves from there. Check with my-oura-mcp auth --status,
forget them with auth --logout.
Personal Access Tokens no longer work: Oura stopped issuing them in December 2025.
Refresh tokens are single-use. Each refresh kills the old one, so two instances sharing a token store knock each other out. The symptom is a
400mentioning single use; the cure is re-runningauthand keeping one instance.
Everything lives in .env (see .env.example). Secrets never reach git.
One codebase, two transports: stdio next to a client on this machine, HTTP on
a server so the web clients and your phone can reach it.
uv run my-oura-mcp install prints these with the absolute path already filled
in. --scope user makes the server visible from any directory; without it, only
from where the command ran. Verify with claude mcp list / codex mcp list.
Nothing is exposed and no network is involved. To debug the transport itself:
uv run my-oura-mcp --transport http --port 8000 — no secret needed on loopback.
This is what makes the server reachable from any device, from Claude.ai and from ChatGPT. Step by step in docs/DEPLOY.md (Russian): how to let traffic in, how to move Oura authorization across, how to connect web clients.
OURA_PUBLIC_URL turns OAuth on: the server becomes its own authorization
server with dynamic client registration, restricted to https://claude.ai and
https://chatgpt.com. Another client needs its exact origin in
OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS; the consent page names the client and its
return origin before asking for the secret.
Two ways to expose it, and the choice is not cosmetic. Caddy is simpler, but its certificate lands in Certificate Transparency — a public log revealing that this address hosts a service. A Cloudflare Tunnel opens no inbound ports at all. If a VPN lives on the same host, only the tunnel will do.
Keep exactly one live instance: Oura's refresh token is single-use, and two servers sharing a token store will knock each other out of authorization.
Three separate bugs came from Oura's date semantics, all of which lost data silently rather than raising an error. Worth knowing if you build against this API yourself:
sleep and daily_activity are filtered by an internal UTC timestamp,
not by the day field Oura itself returns. At UTC+3 a night that starts
after midnight lands in the previous UTC day: asking for 28..28 returns
nothing while the record with day=28 plainly exists. The server widens the
window and trims by day afterwards. Verified by sweeping every endpoint;
the other six behave.heartrate returns timestamps in UTC. Grouping by the first ten
characters of that string splits a local day in two, pushing 00:00–03:00
local into the previous day — exactly the resting heart rate you care about.
Grouping uses OURA_TZ.long_sleep wins, or the longest one; naps are reported separately as
naps_h so their HRV never averages with the night's..env, the token store and the cache are in .gitignore. Verify before
committing: git status --porcelain.600) file
permissions.OURA_MCP_TOKEN using a constant-time
comparison. The access model is deliberately simple: one secret, one owner,
no per-user separation.uv run my-oura-mcp --transport http --host 0.0.0.0./healthz is intentionally open — a reverse proxy needs it, and it returns
nothing but ok.Authorization header from its logs.Older days go into SQLite. The two most recent completed days are rechecked on every request because late syncs can update them; older history is served from the cache without a network call.
uv run my-oura-mcp cache --status # what is cached
uv run my-oura-mcp cache --clear # forget it
Three things worth knowing. Today is never cached — Oura is still writing it. Empty days are not cached either: an empty day means either "did not wear the ring" or "has not synced yet", and the second resolves itself within hours, whereas a cached blank would last forever. The mode is part of the key, so sandbox data cannot surface in production.
Per-minute heart rate bypasses the cache: its rows carry no day field.
Clients that support resources can read oura://today, oura://yesterday,
and oura://week. They provide the same sleep/readiness/activity summaries
as the tools, without choosing arguments manually.
skills/oura ships a Claude-oriented skill — not more tools, but workflows on top of them: whether sleep is actually improving, whether today can take load, what the body was doing on a bad day, whether a change in routine did anything. Each is a sequence of calls plus a way to reason about the answer, which no single tool can express.
Install it by copying into your client's skills directory:
cp -r skills/oura ~/.claude/skills/
The recipes are checked against the code by tests: a field name that no tool
returns fails uv run pytest instead of quietly sending the model nowhere.
Codex can also load these repository skills after copying them to its skills directory:
mkdir -p ~/.codex/skills
cp -R skills/oura skills/oura-mcp-maintenance ~/.codex/skills/
oura interprets data through the MCP server. oura-mcp-maintenance guides
safe changes to this repository and its Claude/ChatGPT/Codex integration.
Claude says there are no Oura tools. The server didn't connect. claude mcp list shows its state. A common cause is a relative path where a full one is
required — uv run my-oura-mcp install prints the command with the right one.
"Авторизация не пройдена — токенов нет". The server is in production mode
but has never signed in to Oura. Run uv run my-oura-mcp auth; check token state
with uv run my-oura-mcp auth --status.
401 against a server on a VPS. OURA_MCP_TOKEN doesn't match. Header
values are sent verbatim, so the word Bearer and the space belong to the value:
Bearer abc123, not abc123.
Data comes back for the wrong day. OURA_TZ isn't set. A server clock is
almost always UTC, so "today" starts hours off from yours and a night's sleep
lands in the previous day. Set it explicitly, e.g. OURA_TZ=Europe/Moscow.
"refresh-токен отвергнут". Oura's refresh token is single-use, and this
happens when a second instance spent it. Keep exactly one alive: once the VPS is
up, point local Claude Code at it too. Recover with my-oura-mcp auth.
Requests to api.ouraring.com fail with SSL_ERROR_SYSCALL or a timeout.
Usually not the server: the client retries four times with backoff. If that
doesn't help, a VPN generally does.
claude.ai won't connect to your server. Check that OURA_PUBLIC_URL is set
and matches the connector URL character for character, including https:// and
no trailing slash. The startup banner says whether OAuth came up. Beyond that,
see docs/DEPLOY.md.
You press Allow on the consent page and nothing happens. Check the server
logs: a POST /oauth/consent returning 303 with no POST /token after it
means the browser blocked the hop back to claude.ai. That is what an over-strict
Content-Security-Policy looks like — and curl cannot reproduce it, since it
does not enforce CSP at all.
"Запрос устарел" / request expired. Authorization requests live in process memory, so restarting the server invalidates any consent page already open. The secret is not the problem — go back to claude.ai and start the connection again.
uv run pytest
Tests never touch the network; Oura's responses are stubbed with respx.
Tool tests go through mcp.call_tool() rather than calling the functions
directly — some bugs only appear on the real protocol layer, where MCP clients
pass declared defaults as explicit arguments.
For Codex and other coding agents, repository instructions and a task/review structure live in AGENTS.md and docs/agents.
x86_64 macOS: cryptography 49+ ships no wheel for this platform and tries
to build from Rust sources. pyproject.toml pins 48.0.0 for it specifically;
Linux and native arm64 are untouched. This bites Apple Silicon too whenever
Homebrew lives in /usr/local rather than /opt/homebrew — check with
file $(which python3).
Flaky network: if requests to api.ouraring.com fail with
SSL_ERROR_SYSCALL or time out, it usually isn't the server. The client makes
four attempts with backoff; beyond that, try a VPN.
See docs/ROADMAP.md for what's planned and what was deliberately deferred.
MIT
© 2026 MCP Directory.
Sleep, readiness, HRV, resting heart rate, activity and stress from your Oura Ring
{ "mcpServers": { "io.github.antvsl-oura-mcp": { "command": "uvx", "args": [ "my-oura-mcp==0.4.2" ], "env": { "OURA_CLIENT_ID": "<value>", "OURA_CLIENT_SECRET": "<secret>", "OURA_REDIRECT_URI": "<value>", "OURA_API_MODE": "<value>", "OURA_TZ": "<value>", "OURA_TOKEN_STORE": "<value>", "OURA_PUBLIC_URL": "<value>", "OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS": "<value>" } } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
The publisher lists these environment variables: OURA_CLIENT_ID, OURA_CLIENT_SECRET, OURA_REDIRECT_URI, OURA_API_MODE, OURA_TZ, OURA_TOKEN_STORE, OURA_PUBLIC_URL, OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS, OURA_MCP_TOKEN.
Oura Ring runs locally over stdio.
Last checked 2026-11-08. Sleep, readiness, HRV, resting heart rate, activity and stress from your Oura Ring