Oura MCP Server for Sleep Data Retrieval

Overview

This MCP (Model Context Protocol) server connects to the Oura API to fetch and surface sleep-related data for downstream applications and model contexts. It performs the OAuth2 handshake with Oura, stores access/refresh tokens securely, and exposes simple HTTP endpoints that return curated sleep metrics in a machine-friendly JSON format. The server is intended for developers who want automated, repeatable access to Oura sleep data for analytics, personal assistants, or model prompt augmentation.

Because the server acts as an intermediary, it centralizes authentication and token management and can be deployed behind standard infrastructure (containers, reverse proxies, secrets managers). Using an MCP-compatible endpoint pattern makes it straightforward to integrate sleep context into AI-driven workflows or pipelines while separating direct API credentials from consuming services.

Features

• OAuth2 integration with Oura Cloud API (authorization + token refresh)
• Endpoints that expose sleep summary and detailed sleep period data
• MCP-oriented endpoints for model context consumption
• Local or containerized deployment, configurable via environment variables
• Minimal dependencies to keep operational surface small
• Automated token refresh to maintain continuous access to user data

Installation / Configuration

Clone the repository and run with Docker or locally (example uses Docker but local builds follow the same env variables).

1. Clone the repo:

git clone https://github.com/tomekkorbak/oura-mcp-server.git
cd oura-mcp-server

2. Build and run with Docker:

docker build -t oura-mcp-server .
docker run -p 8080:8080 \
  -e OURA_CLIENT_ID="your-client-id" \
  -e OURA_CLIENT_SECRET="your-client-secret" \
  -e REDIRECT_URI="https://your-host/callback" \
  -e STORAGE_PATH="/data" \
  oura-mcp-server

Common environment variables

OURA_CLIENT_ID       # Oura OAuth client ID
OURA_CLIENT_SECRET   # Oura OAuth client secret
REDIRECT_URI         # Redirect URI configured for the Oura app
PORT                 # (optional) server listen port, default 8080
STORAGE_PATH         # (optional) where persisted tokens or DB files are stored

If running locally without Docker, you can typically install dependencies and run a start script:

# example for a Node.js project
npm install
npm run start

(Refer to the repository’s package/build files for exact commands if different.)

Available Resources

Below are the typical endpoints exposed by the server. Exact paths may vary — check the repo or the running service’s /openapi or README for precise routes.

Example: request sleep for date

curl "http://localhost:8080/sleep?start=2026-03-01&end=2026-03-07"

Example: request MCP context (POST body can include user id and date range)

curl -X POST http://localhost:8080/mcp/context \
  -H "Content-Type: application/json" \
  -d '{"user":"alice","start":"2026-03-01","end":"2026-03-07"}'

Sample response (abbreviated):

{
  "user": "alice",
  "range": {"start":"2026-03-01","end":"2026-03-07"},
  "sleep_summaries": [
    {"date":"2026-03-01","total_sleep_minutes":420,"score":86},
    {"date":"2026-03-02","total_sleep_minutes":390,"score":80}
  ]
}

Use Cases

• Enrich model prompts with recent sleep context: A personal assistant can include a user’s sleep quality summary when generating daily recommendations.
• Automated reporting pipeline: Periodically pull sleep metrics for cohort analysis and feed them into data warehouses or dashboards.
• Health-focused agents: Deliver personalized coaching by combining sleep trends with activity and readiness scores retrieved via the MCP server.
• Privacy-aware integrations: Keep Oura credentials and refresh tokens confined to the server; downstream services receive only the data they need via structured endpoints.

Concrete example flows

1. Personal assistant

   • User authorizes the Oura account via /authorize.
   • The assistant queries /mcp/context each morning to include sleep quality and duration in a greeting message like “You slept 7.1 hours last night with a sleep score of 82.”

2. Nightly ETL job

   • A scheduler hits /sleep with a date range on a daily basis.
   • The job stores aggregated nightly sleep metrics into a timeseries DB for trend analysis.

Notes and Next Steps

• Review the repository documentation for exact endpoint names and auth flow details.
• Secure deployment: run behind HTTPS, use a secrets manager for client credentials, and restrict access to MCP endpoints as needed.
• If you need additional fields, extend the server to map more Oura API fields into the MCP response schema.

Repository and source: https://github.com/tomekkorbak/oura-mcp-server