Oura MCP server

Oura MCP server

Claude.ai와 Claude Code에서 Oura 링 데이터를 읽어보세요. 수면 점수 뒤에 숨은 전체 수면 주기(periods), 준비도, 활동, 운동, 심박수, 스트레스, SpO2, 회복 탄력성, 심혈관 나이, VO2max, 취침 추천, 태그와 휴식 모드를 확인할 수 있습니다. 이 서버는 문서화된 Oura API v2와 통신하며, OAuth 2.1 로그인을 앞에 두어 Claude.ai에 사용자 지정 커넥터로 추가할 수 있게 해줍니다. Claude Code에서는 일반 토큰을 대신 사용할 수 있습니다.

npm 패키지를 쓰지 않는 이유

이 프로젝트는 @daveramey/oura-mcp를 감싸는 래퍼로 시작했다가, 그 패키지가 요청한 것 대부분에 대해 아무것도 반환하지 않아 대체했습니다. 그 패키지는 단일 일 범위를 start_date == end_date로 조회하는데, Oura API는 그 이름이 암시하는 방식으로 응답하지 않습니다:

• sleep는 UTC의 bedtime_start로 필터링하므로, 현지 시각(UTC+3) 00:31에 시작하는 밤은 이전 UTC 날짜에 해당하여 해당 날짜의 창 밖으로 빠집니다.

• daily_activity와 workout는 end_date를 배타적으로 처리하여, 같은 날짜만으로 구성된 범위는 폭이 0이 됩니다.

그 결과는 조용히 넘어갑니다. oura_sleep은 빈 periods 배열을 가진 점수를, oura_activity는 null을, oura_workouts는 []를 단일 날짜 호출 때마다 반환합니다. 아무 오류도 발생하지 않으므로, "쿼리가 잘못되었다"기보다 "기록된 데이터가 없다"로 읽힙니다. 이 서버는 범위를 양쪽으로 늘리고 각 레코드의 자체 day 필드를 기준으로 다시 걸러내므로 시간대가 맞고, 조용히 한 페이지만 반환하는 대신 next_token을 소진할 때까지 따라갑니다.

도구

날짜를 사용하는 모든 도구는 선택적으로 YYYY-MM-DD 형식의 date를 받고, 기본값은 오늘입니다. Oura는 잠에서 깬 날짜에 밤으로 분류합니다.

oura_vo2_max, oura_sleep_time, oura_cardiovascular_age는 의도적으로 데이터가 드뭅니다. Oura는 매일이 아니라 주기적으로 계산하므로, 빈 결과가 정상이며 동기화 실패가 아닙니다.

작동 과정

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8441
        |
   auth-server.js  :8442    handles the login and the tokens
        |
   oura-mcp  :8440          streamable HTTP, local only
        |
   api.ouraring.com

8440-8442의 포트는 이 호스트의 다른 MCP들과 겹치지 않습니다. :8440에서 실행되는 서버는 자체 로그인이 없고 루프백 외의 주기에는 바인딩을 거부하므로, 항상 로그인 계층을 통해서만 접근됩니다.

설정

Python 3.12 이상과 로그인 계층으로 사용할 Node가 필요합니다.

python3 -m venv .venv
.venv/bin/pip install -e .
npm install --omit=dev

mkdir -p ~/.config/oura-mcp && chmod 700 ~/.config/oura-mcp
echo "OURA_TOKEN=your-personal-access-token" > ~/.config/oura-mcp/env
chmod 600 ~/.config/oura-mcp/env

CONFIG_DIR=~/.config/oura-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/oura-mcp/token
chmod 600 ~/.config/oura-mcp/token

Oura 토큰은 cloud.ouraring.com에서 받으세요.

그런 다음 systemd/*.service와 nginx/oura-mcp.conf에서 YOUR_USER와 호스트명을 채우고:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now oura-mcp oura-mcp-auth
sudo cp nginx/oura-mcp.conf /etc/nginx/sites-enabled/oura-mcp
sudo nginx -t && sudo systemctl reload nginx

127.0.0.1:8441을 가리키는 터널 또는 HTTPS 프록시를 연결하세요. OAuth에는 HTTPS가 필요합니다.

외부에서 확인하세요. 디스커버리가 메타데이터를 반환해야 하고, 토큰 없이 /mcp를 요청하면 401을 반환해야 합니다.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

연동

Claude.ai: 설정 > 커넥터 > 사용자 지정 커넥터 추가, https://your-host/mcp, 클라이언트 ID와 시크릿은 비워 둡니다.

Claude Code:

claude mcp add --transport http oura https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/oura-mcp/token)" --scope user

로그인 계층 없이 stdio로 실행하려면:

OURA_TOKEN=your-token .venv/bin/oura-mcp

출처

로그인 계층은 rollecode/obsidian-remote-mcp에서 나왔습니다.