circle-mcp

가족 프로필 및 프로필별 인터넷 사용량 등 읽기 전용 Circle(Meetcircle/Aura) 자녀 보호 데이터를 노출하는 MCP 서버(stdio)입니다.

API 클라이언트와 인증 흐름이 비롯된 airstream-dashboard Circle 제공자에서 추출되었습니다. 표준 라이브러리만 사용하는 클라이언트이며, 유일한 의존성은 mcp SDK입니다.

도구

Related MCP server: openbanking-mcp

설정

python3 -m venv .venv
.venv/bin/pip install -e .

구성

환경 변수가 우선하며, 시크릿 파일이 나머지를 채웁니다:

CIRCLE_SECRETS_FILE은 circle.<키> = <값> 줄이 있는 conf 파일을 가리키며, 이를 통해 자격 증명을 MCP 클라이언트 구성에 두지 않을 수 있습니다.

Claude Code 등록: .mcp.json.example을 .mcp.json으로 복사하고 자격 증명을 입력합니다(또는 CIRCLE_SECRETS_FILE을 자격 증명이 담긴 conf 파일로 지정). .mcp.json은 일반적으로 자격 증명이나 머신별 경로를 포함하므로 gitignore에 포함됩니다.

API 참고 사항(2026-08)

인증 흐름:

1. POST https://api.aurasvc.io/auth/session/signin — 헤더 Authorization: Public <aura_public_key> 및 본문 {"alias": <email>, "password": ...} 사용 → access_token + refresh_token(/auth/session/refresh_token으로 갱신)

2. POST https://auth.meetcircle-blue.co/api/v2/grant/admin — {"deviceid": <device_id>, "jwt": <access_token>} 사용 → 관리자 토큰

3. https://vc.meetcircle-blue.co의 데이터 엔드포인트 — Authorization: Bearer <admin_token> 사용:

   • /api/LOGS/usage/categories?user=<pid>&day=<d>&ndays=<n>(실제 동작 확인됨)

   • /api/LOGS/usage?user=<pid>&day=<d>&ndays=<n>

   • /api/QUERY/users, /api/QUERY/circleinfo(확인되지 않음)

로그인 시 오류 의미:

• 401 {"message": "NoCredential"} — Authorization: Public <key> 헤더 누락/잘못됨

• 401 {"message": "InvalidCredentials"} — 키는 수락되었으나 사용자 이름/비밀번호가 거부됨