circle-mcp

MCP server (stdio) exposing read-only Circle (Meetcircle/Aura) parental-control data: family profiles and per-profile internet usage.

Extracted from the airstream-dashboard Circle provider, which is where the API client and its auth flow come from. Stdlib-only client; the only dependency is the mcp SDK.

Tools

Related MCP server: openbanking-mcp

Setup

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

Configuration

Environment variables win; a secrets file fills the rest:

CIRCLE_SECRETS_FILE points at a conf file with circle.<key> = <value> lines, which keeps credentials out of your MCP client config.

Claude Code registration: copy .mcp.json.example to .mcp.json and fill in your credentials (or point CIRCLE_SECRETS_FILE at a conf file holding them). .mcp.json is gitignored, since it typically embeds credentials or machine-specific paths.

API notes (2026-08)

Auth flow:

1. POST https://api.aurasvc.io/auth/session/signin with header Authorization: Public <aura_public_key> and body {"alias": <email>, "password": ...} → access_token + refresh_token (refresh via /auth/session/refresh_token)

2. POST https://auth.meetcircle-blue.co/api/v2/grant/admin with {"deviceid": <device_id>, "jwt": <access_token>} → admin token

3. Data endpoints on https://vc.meetcircle-blue.co with Authorization: Bearer <admin_token>:

   • /api/LOGS/usage/categories?user=<pid>&day=<d>&ndays=<n> (verified live)

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

   • /api/QUERY/users, /api/QUERY/circleinfo (unverified)

Error semantics on signin:

• 401 {"message": "NoCredential"} — missing/invalid Authorization: Public <key> header

• 401 {"message": "InvalidCredentials"} — key accepted, username/password rejected