oura-mcp is an open-source project that wraps the Oura Ring v2 API into an MCP (Model Context Protocol) server, allowing AI clients to directly read Oura health data. Its core goal is to solve the problem that the Oura API does not report an error when data is incomplete, but instead returns seemingly complete results.
Purpose and positioning The Oura API does not report an error when it cannot return the requested content, but instead returns other data shaped like a correct response. oura-mcp fully paginates before returning and reports how many pages it actually went through, preventing the model from giving confident but wrong answers based on partial data.
Main capabilities
- Full pagination: if the client does not follow next_token, it will only get the first page. For example, one day of heart rate data is 1,231 records spanning 2 pages; without pagination you can only get 1,000 records (81%), yet it looks like complete data. This server pages to the end before returning.
- Date range correction: end_date behaves inconsistently across collections; workout filters by UTC date but reports by local time. This server requests two extra days on each end and then trims, ensuring the range always includes both ends.
- latest parameter validation: only heartrate and ring_battery_level support latest=true; the other 17 collections ignore it and return the entire collection. This server rejects invalid usage before the request is sent.
- Field filtering feedback: nonexistent fields are silently ignored. This server lists fields that never appeared in ignored_fields.
Tool set Provides six tools, rather than one tool per collection:
- oura_check: checks whether the server is working properly.
- oura_today: returns today's daily_sleep and daily_readiness plus the raw records from the previous 7 days, without any calculations. The days parameter is 1 to 30, default 7.
- oura_collections: lists all 19 collections and their contents and shapes.
- oura_query: queries raw records by collection and start/end dates, and returns the number of pages.
- oura_compare: compares the mean values of a metric between two time periods, giving the difference and the metric's own normal fluctuation band, and outputs outside_noise, within_noise, or cannot_tell three conclusions.
- oura_relate: calculates the correlation between two metrics at a specified lag in days (0-7), removing day-of-week effects and trends, and returns the correlation coefficient, 95% interval, and three conclusions. All tools are read-only; there is no POST, PUT, or DELETE in the package.
How to use
- Sandbox trial: no credentials required, 18 collections available (except personal_info), data is synthetic.
- Installation: download oura-mcp.mcpb and double-click to install into Claude Desktop; or use uvx --from mcp-oura oura-mcp; or pip install mcp-oura.
- Credentials: Oura stopped issuing personal access tokens in December 2025. Existing tokens still work; new tokens require registering an application via OAuth2 at cloud.ouraring.com/oauth/applications, with the redirect address being http://localhost:9876/callback/（末尾斜杠必需）。令牌存储在 ~/.config/oura-mcp/credenciales.json, permissions 600, can refresh automatically, and oura-mcp --forget can clear it.
- Remote use: claude.ai and ChatGPT connect via URL, requiring deployment of ts/worker as your own Cloudflare Worker, for use only with your own Oura account.
Applicable scenarios Suitable for users who want to let an AI assistant directly read and analyze Oura Ring health data and who need to ensure data completeness and statistical rigor.
Limitations
- Remote Worker deployment is experimental and has not yet been verified on a real deployment, a real Oura account, or a full claude.ai/ChatGPT connection.
- oura_compare requires at least 7 days of valid values and 60 days of history to estimate the fluctuation band.
- oura_relate usually requires about three months of data on real data.
- Sandbox data repeats short patterns, so there are insufficient valid pairs.
- No trend tool is provided, because a dedicated slope test captures only a few more points compared with comparing the first and second halves.
