circle-mcp

MCP 服务器（stdio），以只读方式暴露 Circle（Meetcircle/Aura）家长控制数据：家庭档案和每个档案的互联网使用情况。

从 airstream-dashboard Circle 提供程序中提取，API 客户端及其认证流程即来源于此。仅使用标准库的客户端；唯一依赖是 mcp SDK。

工具

Related MCP server: openbanking-mcp

设置

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

配置

环境变量优先；秘密文件填充其余部分：

CIRCLE_SECRETS_FILE 指向一个包含 circle.<key> = <value> 行的配置文件，这样可以将凭据从 MCP 客户端配置中分离出来。

Claude Code 注册：将 .mcp.json.example 复制为 .mcp.json 并填写你的凭据（或将 CIRCLE_SECRETS_FILE 指向包含这些凭据的配置文件）。.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"} — 密钥被接受，但用户名/密码被拒绝