oura-ring-mcp-server
A Model Context Protocol server for the Oura Ring API v2. Point Claude (or any MCP client) at your Oura data and ask about your sleep, readiness, activity, heart rate, workouts, and more.
Built with somamcp (telemetry + introspection),
functype (typed error handling), and zod.
Design
Rather than one tool per endpoint, the server exposes a single consolidated oura_data tool
with a collection parameter. This keeps the tool schema small (low token cost) while covering
every Oura usercollection endpoint. The tool validates that the parameters you pass are legal
for the chosen collection and returns actionable messages when they are not.
Requirements
- Node.js 24+ (pinned in
.nvmrc) - An Oura personal access token — create one at cloud.ouraring.com/personal-access-tokens
Usage
Claude Desktop / Claude Code
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"oura": {
"command": "npx",
"args": ["-y", "oura-ring-mcp-server"],
"env": {
"OURA_API_KEY": "your-personal-access-token"
}
}
}
}
That runs the server over stdio, which is what most MCP clients expect.
Configuration
| Env var | Required | Default | Description |
|---|---|---|---|
OURA_API_KEY | yes | — | Oura personal access token, sent as a Bearer token. |
OURA_SANDBOX | no | false | Use Oura's /sandbox/ demo data instead of your real data. |
TRANSPORT_TYPE | no | stdio | stdio or httpStream. |
PORT | no | 3000 | Port for httpStream transport. |
HOST | no | 0.0.0.0 | Host for httpStream transport. |
OURA_TELEMETRY_FILE | no | — | Write NDJSON telemetry events to this file path (safe under any transport). |
OURA_TELEMETRY_CONSOLE | no | true | Console telemetry, httpStream only (never enabled under stdio). |
HTTP transport
For a long-running / networked deployment:
OURA_API_KEY=... TRANSPORT_TYPE=httpStream PORT=3000 npx -y oura-ring-mcp-server
The MCP endpoint is served at /mcp; somamcp also exposes a public GET /health probe.
The oura_data tool
| Parameter | Applies to | Notes |
|---|---|---|
collection | all | Which data collection to fetch (see below). |
start_date / end_date | daily collections | YYYY-MM-DD. Omitted → last 7 days. |
start_datetime / end_datetime | heartrate, ring_battery_level | ISO-8601. Omitted → last 24 hours. |
latest | heartrate, ring_battery_level | Return only the most recent sample. |
document_id | collections with a detail route | Fetch a single record by id. |
next_token | list collections | Pagination cursor from a previous response. |
fields | list collections | Comma-separated sparse fieldset. |
Collections
Daily (start_date/end_date): daily_activity, daily_sleep, daily_readiness,
daily_spo2, daily_stress, daily_resilience, daily_cardiovascular_age, vO2_max,
sleep, sleep_time, session, workout, tag, enhanced_tag, rest_mode_period
Time-series (start_datetime/end_datetime): heartrate, ring_battery_level
List / singleton: ring_configuration, personal_info
Example prompts
- "What was my average readiness score last week?"
- "Show my sleep stages for the night of 2026-06-20."
- "Get my most recent heart rate reading."
- "How many workouts did I log this month and how long were they?"
Development
pnpm install
pnpm validate # format + lint + typecheck + test + build
pnpm dev # watch build
pnpm inspect # run against the MCP Inspector
Try it without a ring by setting OURA_SANDBOX=true to hit Oura's demo dataset.
License
MIT