circle-mcp

MCP-Server (stdio), der schreibgeschützte Circle (Meetcircle/Aura)-Daten zur Kindersicherung bereitstellt: Familienprofile und Internetnutzung pro Profil.

Aus dem airstream-dashboard Circle-Provider extrahiert, von dem der API-Client und sein Authentifizierungsablauf stammen. Nur-Stdlib-Client; die einzige Abhängigkeit ist das mcp-SDK.

Werkzeuge

Related MCP server: openbanking-mcp

Einrichtung

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

Konfiguration

Umgebungsvariablen haben Vorrang; eine Secrets-Datei füllt den Rest:

CIRCLE_SECRETS_FILE verweist auf eine Konfigurationsdatei mit circle.<key> = <value>-Zeilen, die Anmeldedaten aus deiner MCP-Client-Konfiguration heraushält.

Claude-Code-Registrierung: Kopiere .mcp.json.example zu .mcp.json und fülle deine Anmeldedaten ein (oder verweise mit CIRCLE_SECRETS_FILE auf eine Konfigurationsdatei, die sie enthält). .mcp.json ist gitignored, da es typischerweise Anmeldedaten oder maschinenspezifische Pfade enthält.

API-Hinweise (2026-08)

Authentifizierungsablauf:

1. POST https://api.aurasvc.io/auth/session/signin mit Header Authorization: Public <aura_public_key> und Body {"alias": <email>, "password": ...} → access_token + refresh_token (Aktualisierung über /auth/session/refresh_token)

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

3. Daten-Endpunkte auf https://vc.meetcircle-blue.co mit Authorization: Bearer <admin_token>:

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

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

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

Fehlersemantik bei der Anmeldung:

• 401 {"message": "NoCredential"} — fehlender/ungültiger Authorization: Public <key>-Header

• 401 {"message": "InvalidCredentials"} — Schlüssel akzeptiert, Benutzername/Passwort abgelehnt