oura-mcp

A self-hostable MCP server that exposes your Oura Ring health data as tools for Claude and other MCP-compatible clients. Ask about your sleep, readiness, activity, and heart rate in natural language — the MCP server handles the API calls and returns structured data that AI assistants can reason about.

Designed to run in Docker on home lab infrastructure (e.g. Proxmox), or locally for development.

MCP (Model Context Protocol) lets AI assistants call external tools. This server turns your Oura Ring into one of those tools. Instead of opening the Oura app, you can ask Claude:

• *"How did I sleep last night?"*
• *"Give me a morning health briefing"*
• *"Compare my readiness scores for the past week"*
• *"What's my HRV trend over the last 5 days?"*

┌─────────────────┐       MCP Protocol        ┌─────────────┐      HTTPS       ┌─────────────┐
│  Claude Desktop  │◄─────(stdio or HTTP)─────►│  oura-mcp   │◄────────────────►│  Oura API   │
│  or MCP Client   │                           │  server      │  Bearer token    │  v2          │
└─────────────────┘                            └─────────────┘                  └─────────────┘

Transports supported:

• stdio — Claude Desktop launches the server as a subprocess (recommended for desktop use)
• Streamable HTTP — server runs standalone on port 3333 at /mcp (recommended for Docker / remote access)

Project structure:

src/
  index.ts              Entry point — transport setup, tool registration
  oura-client.ts        All Oura API HTTP calls (centralized)
  utils/
    date.ts             Date resolution ("today", "yesterday", "YYYY-MM-DD")
  tools/
    sleep.ts            get_sleep
    readiness.ts        get_readiness
    activity.ts         get_activity
    heart-rate.ts       get_heart_rate
    summary.ts          get_daily_summary

• Node.js 20+ (for local development)