# Oura Mcp Server

> Oura MCP server for poke.com and other agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-madebydia-oura-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [madebydia](https://agentstack.voostack.com/s/madebydia)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [madebydia](https://github.com/madebydia)
- **Source:** https://github.com/madebydia/oura-mcp-server

## Install

```sh
agentstack add mcp-madebydia-oura-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Oura MCP Server

MCP (Model Context Protocol) server that enables AI assistants to access your Oura Ring health data through OAuth2-authenticated API calls.

Built by [@madebydia](https://x.com/madebydia)

Built for seamless integration with [Poke](https://poke.com) and other MCP-compatible clients. Deploy to Railway for production use or run locally for development.

[](https://railway.com/deploy/oura-mcp-server?referralCode=a6V1Do&utm_medium=integration&utm_source=template&utm_campaign=generic)

## Features

- **OAuth2 with PKCE** - Secure authentication with automatic token refresh
- **9 MCP Tools** - Access sleep, readiness, activity, heart rate, workouts, and more
- **Dual Transport Support** - Both SSE and Streamable HTTP transports
- **Token Encryption** - AES-256-GCM encryption for OAuth tokens at rest
- **Smart Caching** - Reduce API calls with intelligent data caching
- **Rate Limiting** - Built-in protection against API quota exhaustion
- **ngrok Support** - Easy remote access for mobile and cloud integrations

## Prerequisites

- Node.js 18 or higher
- Oura Ring (all generations supported - Gen 2, Gen 3, and Gen 4)
- Oura account with API access
- Railway account (recommended for production deployment) or ngrok (for local development)

## Installation

1. Clone the repository:
```bash
git clone https://github.com/madebydia/oura-mcp-server.git
cd oura-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Copy the example environment file:
```bash
cp .env.example .env
```

4. Generate required secrets:
```bash
# Generate AUTH_TOKEN
openssl rand -hex 32

# Generate TOKEN_ENCRYPTION_KEY
openssl rand -hex 32
```

## Quick Start - Railway Deployment (Recommended)

### Step 1: Deploy to Railway

1. Click the button below to deploy to Railway:

Or manually:
- Go to [Railway](https://railway.app)
- Create new project from GitHub repo
- Connect your fork of this repository

2. Generate required secrets locally:
```bash
# Generate AUTH_TOKEN
openssl rand -hex 32

# Generate TOKEN_ENCRYPTION_KEY
openssl rand -hex 32
```

3. In Railway dashboard, add environment variables:
   - `AUTH_TOKEN` - Your generated auth token
   - `TOKEN_ENCRYPTION_KEY` - Your generated encryption key
   - `NODE_ENV` - Set to `production`
   - `CORS_ORIGIN` - Set to `*` or your specific domain
   - `PORT` - Leave unset (Railway will auto-assign)

4. Wait for deployment to complete and note your Railway URL (e.g., `https://your-app.up.railway.app`)

### Step 2: Register Oura OAuth Application

1. Go to https://cloud.ouraring.com/oauth/applications
2. Click "Create New Application"
3. Fill in:
   - **Application Name:** "Personal MCP Server" (or your choice)
   - **Redirect URI:** `https://your-app.up.railway.app/oauth/callback`
   - **Scopes:** Select all available scopes
4. Save the **Client ID** and **Client Secret**

### Step 3: Configure OAuth Credentials in Railway

Add these environment variables in Railway dashboard:
- `OURA_CLIENT_ID` - Your Oura client ID
- `OURA_CLIENT_SECRET` - Your Oura client secret
- `OURA_REDIRECT_URI` - `https://your-app.up.railway.app/oauth/callback`

Railway will automatically redeploy with the new configuration.

## Local Development Setup

### Step 1: Set up ngrok

1. Install and authenticate ngrok:
```bash
ngrok config add-authtoken YOUR_NGROK_TOKEN
```

2. Start ngrok tunnel:
```bash
ngrok http 3001
```

3. Note your ngrok URL (e.g., `https://your-domain.ngrok.dev`)

### Step 2: Configure Environment Variables

Copy `.env.example` to `.env` and configure:

```env
# MCP Server Authentication
AUTH_TOKEN=

# Oura OAuth Credentials
OURA_CLIENT_ID=
OURA_CLIENT_SECRET=
OURA_REDIRECT_URI=https://your-domain.ngrok.dev/oauth/callback

# Server Configuration
PORT=3001
NODE_ENV=development

# Token Encryption
TOKEN_ENCRYPTION_KEY=

# CORS Origin
CORS_ORIGIN=*

# Logging (optional)
LOG_LEVEL=info  # Options: error, warn, info, debug
```

## Usage

### Starting the Server

1. Build the TypeScript code:
```bash
npm run build
```

2. Start the server:
```bash
npm start
```

For development with auto-reload:
```bash
npm run dev
```

### Connecting Your Oura Account

1. Open your browser to your server's `/oauth/authorize` endpoint:
   - Railway: `https://your-app.up.railway.app/oauth/authorize`
   - ngrok: `https://your-domain.ngrok.dev/oauth/authorize`
   - Local: `http://localhost:3001/oauth/authorize`
2. Log in to your Oura account
3. Approve the requested permissions
4. You'll be redirected back with a success message

### Connecting to MCP Clients

#### Poke

1. Open Poke app
2. Go to Settings → Integrations → Add Integration
3. Select "Model Context Protocol (MCP)"
4. Enter:
   - **Name:** Oura
   - **Server URL:** `https://your-app.up.railway.app/sse` (or your deployment URL)
   - **API Key:** Your `AUTH_TOKEN` from environment variables
5. Tap "Add Integration"

The server supports both SSE and Streamable HTTP transports for maximum compatibility.

#### Other MCP Clients

Configure your MCP client with:
- **Server URL:** `https://your-app.up.railway.app/sse` (or your deployment URL)
- **API Key (Bearer Token):** Your `AUTH_TOKEN` from environment variables

## Available MCP Tools

### 1. get_personal_info
Get user's personal information and ring details.

### 2. get_sleep_summary
Get sleep data for a date range.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD
- `include_hrv` (optional): boolean

### 3. get_readiness_score
Get daily readiness scores.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD

### 4. get_activity_summary
Get activity data for a date range.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD

### 5. get_heart_rate
Get heart rate data in 5-minute intervals.

**Parameters:**
- `start_datetime` (required): ISO 8601 format
- `end_datetime` (optional): ISO 8601 format

### 6. get_workouts
Get workout sessions.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD

### 7. get_sleep_detailed
Get detailed sleep period data with heart rate and HRV.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD

### 8. get_tags
Get user-created tags and notes.

**Parameters:**
- `start_date` (required): YYYY-MM-DD
- `end_date` (optional): YYYY-MM-DD

### 9. get_health_insights
Get AI-powered insights based on recent data.

**Parameters:**
- `days` (optional): Number of days to analyze (default: 7)

## API Endpoints

### Health Check
```
GET /health
```
Returns server status, OAuth connection status, and cache statistics.

### OAuth Endpoints
```
GET  /oauth/authorize     - Start OAuth flow
GET  /oauth/callback      - OAuth callback (automatic)
GET  /oauth/status        - Get connection status (requires auth)
POST /oauth/disconnect    - Disconnect and clear tokens (requires auth)
```

### MCP Endpoints

The server supports both transport modes:

**Streamable HTTP (recommended for Poke):**
```
POST /sse                 - JSON-RPC requests with direct responses
```

**Classic SSE:**
```
GET  /sse                 - Establish SSE connection
POST /message             - Send JSON-RPC requests via session
```

## Security

### Token Encryption
All OAuth tokens are encrypted at rest using AES-256-GCM encryption.

### Authentication
MCP endpoints require Bearer token authentication:
```
Authorization: Bearer YOUR_AUTH_TOKEN
```

### Rate Limiting
- MCP endpoints: 100 requests per 15 minutes per IP
- Oura API: 5000 requests per day (tracked automatically)

### CORS
Configure allowed origins in `.env` with `CORS_ORIGIN`.

### Logging

The server uses structured logging with configurable log levels:

- **`error`** - Only critical errors (recommended for production)
- **`warn`** - Warnings and errors
- **`info`** - Key operations, warnings, and errors (default)
- **`debug`** - Full verbosity including request/response bodies

Configure via the `LOG_LEVEL` environment variable:

```bash
LOG_LEVEL=info  # Default - balanced logging
LOG_LEVEL=error # Production - minimal output
LOG_LEVEL=debug # Development - verbose debugging
```

**What gets logged at each level:**

- **Error**: Authentication failures, API errors, OAuth failures, rate limits
- **Warn**: Invalid API key attempts, missing SSE sessions
- **Info**: SSE connections, tool executions, OAuth operations, MCP method calls
- **Debug**: Full JSON-RPC requests/responses, connection lifecycle events

## Troubleshooting

### OAuth Callback Failed
- Verify redirect URI matches exactly in Oura app settings
- Ensure your server is accessible (Railway deployed or ngrok running for local)
- Check `OURA_CLIENT_ID` and `OURA_CLIENT_SECRET` are correct
- Confirm `OURA_REDIRECT_URI` matches your deployment URL

### Token Refresh Failed
- Verify `TOKEN_ENCRYPTION_KEY` is set correctly and hasn't changed
- Check `tokens.json` file exists and is readable
- Ensure refresh token hasn't been revoked in Oura account
- For Railway: Check that persistent storage is enabled

### Rate Limit Exceeded
- Caching is built-in with 5-minute default TTL
- Reduce polling frequency in your MCP client
- Check rate limit headers in API responses
- Monitor usage at `/health` endpoint

### Railway-Specific Issues

**Server not starting:**
- Check Railway logs for errors
- Verify all required environment variables are set
- Ensure `PORT` variable is NOT set (Railway auto-assigns)
- Check build logs for TypeScript compilation errors

**OAuth redirect failing:**
- Verify `OURA_REDIRECT_URI` uses your Railway domain
- Check that Railway deployment is public (not private networking only)
- Ensure HTTPS is used in redirect URI (Railway provides this automatically)

**Tokens not persisting:**
- Railway provides persistent storage by default for `tokens.json`
- Check application logs for file write errors
- Verify disk usage hasn't exceeded limits

### Local Development Issues

**ngrok connection issues:**
- Restart ngrok tunnel
- Update `OURA_REDIRECT_URI` if ngrok URL changed
- Verify ngrok authentication token is valid
- Check ngrok isn't blocked by firewall

## Development

### Project Structure
```
oura-mcp-server/
├── src/
│   ├── index.ts              # Main server file
│   ├── oauth/
│   │   ├── handler.ts        # OAuth flow handler
│   │   └── tokens.ts         # Token management
│   ├── mcp/
│   │   ├── server.ts         # MCP protocol implementation
│   │   └── tools.ts          # Tool definitions
│   ├── oura/
│   │   ├── client.ts         # Oura API client
│   │   └── types.ts          # TypeScript types
│   ├── utils/
│   │   ├── encryption.ts     # Token encryption
│   │   ├── cache.ts          # Data caching
│   │   └── validation.ts     # Input validation
│   └── middleware/
│       ├── auth.ts           # Authentication middleware
│       └── errorHandler.ts   # Error handling
├── .env                      # Environment variables (gitignored)
├── tokens.json               # Encrypted tokens (gitignored)
├── package.json
├── tsconfig.json
└── README.md
```

### Running Tests
```bash
npm test
```

### Type Checking
```bash
npm run typecheck
```

### Linting
```bash
npm run lint
```

## Deployment Options

### Option 1: Railway (Recommended)
- **Cost:** Free tier available, pay-as-you-grow
- **Setup Time:** ~5 minutes
- **Benefits:**
  - Always available (24/7 uptime)
  - Automatic deployments from GitHub
  - Built-in HTTPS
  - No server management required
  - Persistent storage for tokens
- **Best for:** Production use, mobile access, sharing with others

### Option 2: Local Development
- **Cost:** Free (ngrok free tier)
- **Setup Time:** ~10 minutes
- **Benefits:**
  - Complete data privacy (tokens stay local)
  - No hosting costs
  - Full control over environment
- **Limitations:**
  - Requires computer to be running
  - ngrok URL changes on restart (free tier)
- **Best for:** Development, testing, personal use

### Option 3: Cloud VM (VPS)
- Deploy to DigitalOcean, AWS EC2, Google Cloud, etc.
- Always available with static IP
- More control but requires server management

### Option 4: Docker
```bash
docker build -t oura-mcp-server .
docker run -p 3001:3001 --env-file .env oura-mcp-server
```

Can be deployed to any Docker-compatible platform (Fly.io, Render, etc.)

## License

MIT

## Support

For issues or questions:
- GitHub Issues: https://github.com/madebydia/oura-mcp-server/issues
- Oura API Docs: https://cloud.ouraring.com/docs
- MCP Protocol: https://modelcontextprotocol.io

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [madebydia](https://github.com/madebydia)
- **Source:** [madebydia/oura-mcp-server](https://github.com/madebydia/oura-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-madebydia-oura-mcp-server
- Seller: https://agentstack.voostack.com/s/madebydia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.