Oura MCP server

oura-mcp

English | 简体中文 | 한국어 | Español

<!-- The Glama badge is live, not a screenshot: it renders whatever that independent index scores this server at today. A badge that can only go up is decoration; one that can drop is evidence. -->

The Oura v2 API as an MCP server. All 19 collections, four tools, no dependencies beyond the MCP SDK.

One local day of heart rate is 1,231 samples across 2 pages

A client that doesn't follow Oura's nexttoken returns 1,000 of them — 81%, looking complete, with nothing saying otherwise.** Measured against the real API on 9 August 2026, one person, one ring, 24 hours.

The test to apply to any Oura MCP server, including this one: does it take next_token — or a cursor, or a limit — as a tool parameter? If it does, pagination is the model's job, and a model that forgets to ask again produces a confident answer off partial data. This server paginates to exhaustion before it returns, and tells you how many pages it took.

That's one of four ways Oura under-delivers without saying so. All four are measured below, and all four are corrected here.

Install

Download oura-mcp.mcpb from the latest release and double-click it. Claude Desktop does the rest — no terminal, no Python, no Node. It runs on Oura's official sample data out of the box, and every sample response says so, so nothing can pass for your own sleep.

Prefer the command line? uvx --from mcp-oura oura-mcp.

Prefer no Python on your machine at all?

docker run -i --rm -e OURA_SANDBOX=1 ghcr.io/proscar87/oura-mcp

-i is not optional: an MCP server speaks over stdin and stdout, not over a port. Without it the container has no stdin, the handshake never arrives, and the client reports a server that doesn't show up.

The problem, measured

Oura does not return errors when it can't give you what you asked for. It returns something different, shaped like a correct response. These are the four we found by measuring against the real API on 9 August 2026:

1. Skip the pagination and you get a fraction

{ "data": [ ... ], "next_token": "eyJ0eXAiOi..." }

If nexttoken comes back and you don't follow it, you receive the first page and nothing warns you. One local day of heartrate — one person, one ring, 24 hours — is 1,231 samples across 2 pages**. A client that doesn't paginate gets 1,000 of 1,231: 81%, looking complete. A month is ~37,000.

2. Asking for a single day returned zero records

enddate does not behave the same across collections**:

And on top of that, workout filters by UTC date while reporting day in local time: at -06:00, asking for July 16–18 returned records from the 15th and 16th — before the requested start.

Here the range is inclusive on both ends, always. Two extra days are requested on each side and then trimmed, which is correct whichever way a given collection behaves — and stays correct when Oura changes it.

3. latest=true is ignored where it doesn't apply

Shortened. The full README is on GitHub.