{
  "markdown": "# Oura MCP Server\n\n[![npm version](https://img.shields.io/npm/v/oura-ring-mcp.svg)](https://www.npmjs.com/package/oura-ring-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![CI](https://github.com/mitchhankins01/oura-ring-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mitchhankins01/oura-ring-mcp/actions/workflows/ci.yml)\n\nAn MCP server that connects your Oura Ring to Claude and other AI assistants. Get human-readable insights about your sleep, readiness, and activity—not just raw JSON.\n\n## Features\n\n<img src=\"docs/outputs/demo.gif\" width=\"500\" alt=\"Demo\">\n\n- **Smart formatting** - Durations in hours/minutes, scores with context (\"85 - Optimal\")\n- **Sleep analysis** - Sleep stages, efficiency, HRV, and biometrics\n- **Readiness tracking** - Recovery scores and contributor breakdown\n- **Activity data** - Steps, calories, and intensity breakdown\n- **Health metrics** - Heart rate, SpO2, stress, cardiovascular age\n- **Smart analysis** - Anomaly detection, correlations, trend analysis\n- **Tags support** - Compare metrics with/without conditions\n\n[See example outputs](docs/outputs/EXAMPLES.md) — what Claude returns for sleep, readiness, weekly summaries, and smart analysis\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g oura-ring-mcp\n```\n\nOr use directly with npx (no install needed):\n```bash\nnpx oura-ring-mcp\n```\n\n### 2. Authenticate with Oura\n\n**Option A: Personal Access Token (simpler)**\n\n1. Go to [cloud.ouraring.com/personal-access-tokens](https://cloud.ouraring.com/personal-access-tokens)\n2. Create a new token\n3. Set `OURA_ACCESS_TOKEN` in your Claude Desktop config (see below)\n\n**Option B: OAuth CLI Flow**\n\n1. Create an OAuth app at [developer.ouraring.com](https://developer.ouraring.com/applications)\n   - Set Redirect URI to `http://localhost:3000/callback`\n2. Run the auth flow:\n   ```bash\n   export OURA_CLIENT_ID=your_client_id\n   export OURA_CLIENT_SECRET=your_client_secret\n   npx oura-ring-mcp auth\n   ```\n3. Credentials are saved to `~/.oura-mcp/credentials.json`\n\n### 3. Configure Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n**With Personal Access Token:**\n```json\n{\n  \"mcpServers\": {\n    \"oura\": {\n      \"command\": \"npx\",\n      \"args\": [\"oura-ring-mcp\"],\n      \"env\": {\n        \"OURA_ACCESS_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n**With OAuth (after running `npx oura-ring-mcp auth`):**\n```json\n{\n  \"mcpServers\": {\n    \"oura\": {\n      \"command\": \"npx\",\n      \"args\": [\"oura-ring-mcp\"]\n    }\n  }\n}\n```\n\nThe server reads credentials from `~/.oura-mcp/credentials.json`. To enable automatic token refresh, add your OAuth credentials:\n\n```json\n{\n  \"mcpServers\": {\n    \"oura\": {\n      \"command\": \"npx\",\n      \"args\": [\"oura-ring-mcp\"],\n      \"env\": {\n        \"OURA_CLIENT_ID\": \"your_client_id\",\n        \"OURA_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Requires Node >=18.\n\n## What Can I Ask?\n\n**Daily check-ins:**\n- \"How did I sleep last night?\"\n- \"Am I recovered enough to work out today?\"\n- \"What's my body telling me right now?\"\n\n**Patterns & trends:**\n- \"Do I sleep better on weekends?\"\n- \"What time should I go to bed for optimal sleep?\"\n- \"Is my HRV improving or declining?\"\n\n**Correlations & insights:**\n- \"Does alcohol affect my sleep quality?\"\n- \"What predicts my best sleep nights?\"\n- \"How does exercise timing affect my recovery?\"\n\n**Comparisons:**\n- \"Compare my sleep this week vs last week\"\n- \"How do I sleep after meditation vs without?\"\n- \"What changed when I started taking magnesium?\"\n\n**Anomalies:**\n- \"Are there any unusual readings in my data?\"\n- \"Why was my readiness so low yesterday?\"\n- \"Find days where my metrics were off\"\n\n## Available Tools\n\n### Data Retrieval\n\n| Tool | Description |\n|------|-------------|\n| `get_sleep` | Sleep data with stages, efficiency, HR, HRV |\n| `get_daily_sleep` | Daily sleep scores with contributors |\n| `get_readiness` | Readiness scores and recovery metrics |\n| `get_activity` | Steps, calories, intensity breakdown |\n| `get_workouts` | Workout sessions with type and intensity |\n| `get_sessions` | Meditation and relaxation sessions |\n| `get_heart_rate` | HR readings throughout the day |\n| `get_stress` | Stress levels and recovery time |\n| `get_spo2` | Blood oxygen and breathing disturbance |\n| `get_tags` | User-created tags and notes |\n\n### Smart Analysis\n\n| Tool | Description |\n|------|-------------|\n| `detect_anomalies` | Find unusual readings using outlier detection |\n| `analyze_sleep_quality` | Sleep analysis with trends, patterns, debt |\n| `correlate_metrics` | Find correlations between health metrics |\n| `compare_periods` | Compare this week vs last week |\n| `compare_conditions` | Compare metrics with/without a tag |\n| `best_sleep_conditions` | What predicts your good vs poor sleep |\n| `analyze_hrv_trend` | HRV trend with rolling averages |\n\n## Resources\n\n| Resource | Description |\n|----------|-------------|\n| `oura://today` | Today's health summary |\n| `oura://weekly-summary` | Last 7 days with averages |\n| `oura://baseline` | Your 30-day averages and normal ranges |\n| `oura://monthly-insights` | 30-day analysis with trends and anomalies |\n| `oura://tag-summary` | Your tags and usage frequency |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `weekly-review` | Comprehensive weekly health review |\n| `sleep-optimization` | Identify what leads to your best sleep |\n| `recovery-check` | Should you train hard or rest today? |\n| `compare-weeks` | This week vs last week comparison |\n| `tag-analysis` | How a specific tag affects your health |\n\n## Remote Deployment (Railway)\n\nDeploy the MCP server for remote access. The server proxies OAuth through Oura, so users authenticate directly with their Oura account — no PAT needed.\n\n### 1. Create an Oura OAuth App\n\n1. Go to [Oura OAuth Applications](https://cloud.ouraring.com/oauth/applications)\n2. Create a new application\n3. Set the **Redirect URI** to: `https://your-app.railway.app/oauth/callback`\n4. Note the **Client ID** and **Client Secret**\n\n### 2. Deploy\n\n```bash\n# Install Railway CLI\nnpm install -g @railway/cli\n\n# Login, init, and deploy\nrailway login\nrailway init\nrailway up\n```\n\n### 3. Set Environment Variables\n\nIn the Railway dashboard, add:\n\n| Variable | Description |\n|----------|-------------|\n| `OURA_CLIENT_ID` | From your Oura OAuth app |\n| `OURA_CLIENT_SECRET` | From your Oura OAuth app |\n| `NODE_ENV` | `production` |\n| `MCP_SECRET` | *(Optional)* Static bearer token for Claude Desktop (`openssl rand -base64 32`) |\n| `OURA_ACCESS_TOKEN` | *(Optional)* PAT fallback if not using OAuth (`MCP_SECRET` required) |\n\nRailway automatically sets `PORT` and `RAILWAY_PUBLIC_DOMAIN`.\n\n### 4. Connect from Claude.ai\n\nUse the **connector** in Claude.ai:\n1. Go to Settings > MCP Connectors > Add\n2. Enter your server URL: `https://your-app.railway.app` (without `/mcp`)\n3. Leave OAuth Client ID and Secret empty (dynamic registration handles it)\n4. You'll be redirected to Oura to authorize access to your data\n\n### 5. Connect from Claude Desktop\n\nFor Claude Desktop, use `MCP_SECRET` + `OURA_ACCESS_TOKEN`:\n\n```json\n{\n  \"mcpServers\": {\n    \"oura-remote\": {\n      \"url\": \"https://your-app.railway.app/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_mcp_secret_here\"\n      }\n    }\n  }\n}\n```\n\n### Local Testing\n\n```bash\n# With Oura OAuth (full flow)\nOURA_CLIENT_ID=your_id OURA_CLIENT_SECRET=your_secret pnpm start:http\n\n# With static secret only (requires OURA_ACCESS_TOKEN)\nOURA_ACCESS_TOKEN=your_pat MCP_SECRET=test-secret pnpm start:http\n\n# Verify health endpoint\ncurl http://localhost:3000/health\n\n# Check OAuth metadata (only available when OURA_CLIENT_ID is set)\ncurl http://localhost:3000/.well-known/oauth-authorization-server\n\n# Test authenticated request (with static secret)\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer test-secret\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{\"capabilities\":{}},\"id\":1}'\n```\n\n## Contributing\n\nSee [CLAUDE.md](CLAUDE.md) for architecture details and development guidelines.\n\n## License\n\nMIT\n",
  "bytes": 8177,
  "sha": "5a24755ac803339cfbe03d1a9ff69cd731328f1de581ababd9068984359a8d46",
  "repo_slug": "mitchhankins01/oura-ring-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mitchhankins01_oura_ring_mcp_1b84c076/readme"
}