# Oura MCP Server

A remote Model Context Protocol (MCP) server for accessing Oura Ring data over Streamable HTTP.

This server is designed for deployment behind HTTPS, such as a self-hosted Coolify instance, so it can be added to Claude.ai as a Custom Connector. It uses the MCP TypeScript SDK's `StreamableHTTPServerTransport`, not stdio and not the legacy SSE transport.

## Setup

### Prerequisites
- Node.js 22+
- pnpm
- Oura account

### Installation
1. Clone the repository
2. Run:
```
pnpm install
pnpm run build
```
## Configuration

### Environment Variables

Create a `.env` file for local development only:
```
PORT=3000
MCP_ALLOWED_HOSTS=oura-mcp.mydomain.com
OURA_PERSONAL_ACCESS_TOKEN=your_token
```

Do not commit `.env` or any real Oura token. In Coolify, set `OURA_PERSONAL_ACCESS_TOKEN` in the Resource environment variable UI.
You can also set `MCP_ALLOWED_HOSTS` to your connector hostname, for example `oura-mcp.mydomain.com`, to restrict accepted Host headers.

### Obtaining An Oura Token

1. Log in to [Oura Cloud Console](https://cloud.ouraring.com/).
2. Create a Personal Access Token at [Personal Access Tokens](https://cloud.ouraring.com/personal-access-tokens).
3. Store it only as `OURA_PERSONAL_ACCESS_TOKEN` in your deployment environment.

## Local Usage

```
pnpm run build
PORT=3000 OURA_PERSONAL_ACCESS_TOKEN=placeholder pnpm start
```

The MCP endpoint is:

```
http://localhost:3000/mcp
```

## Docker

Build and run locally:

```
docker build -t oura-mcp .
docker run --rm -p 3000:3000 -e OURA_PERSONAL_ACCESS_TOKEN=your_token oura-mcp
```

## Coolify Deployment

1. Push this repository to your GitHub account, or use Coolify's Public Repository option with your fork URL.
2. In Coolify, create a new Project if needed.
3. Add a new Resource.
4. Choose your Git repository, or choose Public Repository and paste the repository URL.
5. Select Dockerfile as the build pack.
6. Confirm the Dockerfile path is `Dockerfile`.
7. Set Port Exposes to `3000`.
8. In Environment Variables, add:
   ```
   OURA_PERSONAL_ACCESS_TOKEN=<your Oura personal access token>
   ```
   Do not put the token in code, `.env.example`, build arguments, or logs.
9. Optional but recommended: add `MCP_ALLOWED_HOSTS` with only the hostname from your FQDN, for example:
   ```
   MCP_ALLOWED_HOSTS=oura-mcp.mydomain.com
   ```
10. Set the Resource FQDN/domain field, for example:
   ```
   https://oura-mcp.mydomain.com
   ```
11. Deploy. Coolify will route HTTPS traffic to the container and provision a Let's Encrypt certificate for the FQDN.

Your final Claude Custom Connector URL should be:

```
https://oura-mcp.mydomain.com/mcp
```

## MCP Handshake Check

After deployment, replace the URL below with your actual HTTPS FQDN:

```
curl -i https://oura-mcp.mydomain.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-handshake","version":"1.0.0"}}}'
```

A healthy response returns HTTP 200, an `mcp-session-id` response header, and a JSON-RPC `result` containing the server info for `oura-provider`.

## Available Resources
- `personal_info` - User profile
- `daily_activity` - Activity summaries
- `daily_readiness` - Readiness scores
- `daily_sleep` - Sleep summaries
- `sleep` - Detailed sleep data
- `sleep_time` - Sleep timing
- `workout` - Workout data
- `session` - Session data
- `daily_spo2` - SpO2 measurements
- `rest_mode_period` - Rest periods
- `ring_configuration` - Ring config
- `daily_stress` - Stress metrics
- `daily_resilience` - Resilience metrics
- `daily_cardiovascular_age` - CV age
- `vO2_max` - VO2 max data

## Available Tools
For date-based resources, use tools like `get_daily_sleep` with `startDate` and `endDate` parameters (YYYY-MM-DD).