mcp-oura

A Model Context Protocol server that gives Claude, or any MCP client, read-only access to your Oura Ring data through the Oura API v2. It runs on your computer and talks only to Oura's API.

Ask things like:

• "How did I sleep last night compared with my 30-day average?"

• "Has my VO2 max improved over the past year?"

• "What was my heart rate during yesterday's workout?"

• "Which weekdays do I sleep worst, by month, since January?"

Tools

Every tool is read-only. Dates are YYYY-MM-DD in your local timezone. Oura files a night's sleep under the morning you woke up, so "last night" is today's date. Tools that take a range default to the 7 days ending today.

The server evens out the API's quirks, so every tool covers exactly the dates asked for. docs/design.md lists them.

Related MCP server: Oura MCP Server

Requirements

• An Oura Ring and an active Oura Membership. Without a membership, Oura's API answers 403.

• macOS or Linux, with uv, which installs Python 3.12 or newer if needed.

Setup

1. Install

uv tool install git+https://github.com/lyzetam/mcp-oura

This puts mcp-oura in ~/.local/bin. If your shell can't find it, run uv tool update-shell and open a new terminal. To work on the code instead, see CONTRIBUTING.md.

2. Create an Oura API application

Oura grants API access through OAuth applications. Its API reference says personal access tokens were retired in December 2025. You create your own application: only you use it, and its secret stays on your computer.

1. Sign in at developer.ouraring.com with your Oura account and choose Create New.

2. Fill in the form. Oura asks for a display name, a description, a contact email, and website, privacy policy and terms of service addresses; for a personal application, a link to this repository serves for all three addresses.

3. Add the redirect URI http://localhost:8765/callback, exactly as written.

4. Tick every scope except Email, accept the Oura API Agreement, and create the application.

5. Copy the client ID and client secret it shows you.

3. Sign in

mcp-oura login --client-id <client id>

It asks for the client secret without echoing it, then opens Oura in your browser. Approve access, and the saved credentials refresh themselves from then on. mcp-oura logout revokes both tokens with Oura and deletes the saved credentials.

mcp-oura login also reads OURA_CLIENT_ID and OURA_CLIENT_SECRET, but typing the secret at the prompt keeps it out of your shell history. The sign-in address is also printed in the terminal.

Oura sends your browser back to localhost on the computer the browser runs on. To sign in on a remote machine, forward the port from your own computer first:

ssh -L 8765:localhost:8765 <host>
mcp-oura login --no-browser --client-id <client id>   # on the remote machine

Then open the printed address in your local browser.

A personal access token issued before Oura retired them may still work. Skip steps 2 and 3 and pass it in the client's configuration, for example claude mcp add --scope user oura -e OURA_ACCESS_TOKEN=<token> -- mcp-oura, but expect Oura to refuse it at some point.

4. Connect Claude

Claude Code:

claude mcp add --scope user oura -- mcp-oura

Claude Desktop: quit the app first, because a running Desktop can write its own copy of the configuration back over your edit. Add the server to claude_desktop_config.json (Settings, Developer, Edit Config) with the full path that which mcp-oura prints, then start the app:

{
  "mcpServers": {
    "oura": { "command": "/Users/you/.local/bin/mcp-oura" }
  }
}

Other MCP clients start mcp-oura the same way: a stdio server with no arguments.

5. Check it works

claude mcp list should show oura as connected. Then ask Claude "How did I sleep last night?".

Configuration

Every setting is optional. Claude Desktop does not see your shell's environment, and other clients may not either, so set variables in the client's server configuration: claude mcp add --scope user oura -e OURA_TIMEZONE=Europe/London -- mcp-oura for Claude Code, or an "env": { ... } object next to "command" for Claude Desktop.

Updating and uninstalling

uv tool upgrade mcp-oura                 # update

mcp-oura logout                          # uninstall: revoke and delete the saved credentials,
uv tool uninstall mcp-oura
claude mcp remove --scope user oura      # remove it from Claude,
rm -r ~/.config/mcp-oura                 # and remove the lock file logout leaves

Privacy and security

• The server sends your data only to the MCP client that started it, and keeps no copy. The client passes tool results to its language model: with Claude, they go to Anthropic as part of the conversation, under your Claude account's privacy settings.

• It writes two files, both in ~/.config/mcp-oura/ (created with mode 0700). credentials.json holds your client ID, client secret, access token and refresh token. It has mode 0600 and is replaced atomically on each refresh. An empty credentials.json.lock coordinates refreshes between servers and stays after logout.

• Tokens and the client secret never appear in logs, error messages or tool results.

• Sign-in uses PKCE and a state check, and listens for Oura's redirect only on this computer's loopback addresses (127.0.0.1 and ::1).

• If the credentials file ever leaks, run mcp-oura logout, which revokes both tokens with Oura. The file also holds your application's client secret: reset it on the application's page at developer.ouraring.com (Reset Secret), then run mcp-oura login again with the new secret.

Report vulnerabilities as described in SECURITY.md.

Troubleshooting

If a client shows the server as failed, run mcp-oura in a terminal with the same environment variables the client sets. It either prints the problem and exits, or waits silently, which means it started; the first tool call is what tests the sign-in. Press Ctrl-D to stop it.

Development

git clone https://github.com/lyzetam/mcp-oura && cd mcp-oura
uv sync
uv run pytest --cov     # runs against an in-memory fake of the Oura API; no account needed
uv run ruff check . && uv run ruff format --check . && uv run mypy

CONTRIBUTING.md covers the workflow, and docs/design.md explains how the server is put together. Changes are listed in CHANGELOG.md.

License

MIT