circle-mcp

Servidor MCP (stdio) que expone datos de control parental de solo lectura de Circle (Meetcircle/Aura): perfiles familiares y uso de internet por perfil.

Extraído del proveedor de Circle de airstream-dashboard, que es de donde provienen el cliente de API y su flujo de autenticación. Cliente que usa solo la biblioteca estándar; la única dependencia es el SDK mcp.

Herramientas

Related MCP server: openbanking-mcp

Instalación

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

Configuración

Las variables de entorno tienen prioridad; un archivo de secretos completa el resto:

CIRCLE_SECRETS_FILE apunta a un archivo de configuración con líneas circle.<key> = <value>, lo que mantiene las credenciales fuera de la configuración de tu cliente MCP.

Registro en Claude Code: copia .mcp.json.example a .mcp.json y completa tus credenciales (o apunta CIRCLE_SECRETS_FILE a un archivo de configuración que las contenga). .mcp.json está ignorado por Git, ya que normalmente incrusta credenciales o rutas específicas de la máquina.

Notas de la API (2026-08)

Flujo de autenticación:

1. POST https://api.aurasvc.io/auth/session/signin con la cabecera Authorization: Public <aura_public_key> y el cuerpo {"alias": <email>, "password": ...} → access_token + refresh_token (renovación mediante /auth/session/refresh_token)

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

3. Endpoints de datos en https://vc.meetcircle-blue.co con Authorization: Bearer <admin_token>:

   • /api/LOGS/usage/categories?user=<pid>&day=<d>&ndays=<n> (verificado en directo)

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

   • /api/QUERY/users, /api/QUERY/circleinfo (no verificado)

Semántica de errores en el inicio de sesión:

• 401 {"message": "NoCredential"} — cabecera Authorization: Public <key> ausente o no válida

• 401 {"message": "InvalidCredentials"} — clave aceptada, usuario/contraseña rechazados