circle-mcp
Summary: This server exposes a read-only view of Circle (Aura) parental-control data — the family's profiles and their internet usage — over MCP (stdio or bearer-key HTTP).
List family profiles (
list_profiles): get each profile'spid, name and type; thepidis the key for all usage queries.Get per-profile usage (
get_usage): internet usage for one profile over a window, chosen byprofile_pid(falls back to a configured default),day(days ago to start, 0 = today) andndays(window length) — e.g. the last week isday=6, ndays=7.Get usage by category (
get_usage_categories): the same window broken down into categories like games, social and video.Get Circle-wide status (
get_circle_status): account/device state for the Circle itself.
Notes:
Everything is read-only: no pause/resume, profile edits, device management or other write operations are registered in this schema (the README's write tools need
CIRCLE_MCP_ALLOW_WRITES, and many other read tools it documents — e.g.list_devices,get_history,get_circle_snapshot— are not exposed here).Requires Circle account credentials (
CIRCLE_USERNAME/CIRCLE_PASSWORDplus device ID and Aura key); over HTTP every request needs a bearer key and Circle auth failures surface as tool errors (with a 15-min backoff after a rejected sign-in).
Provides read-only access to Circle parental-control data, including family profiles, per-profile internet usage details, usage by category (games, social, video, etc.), and Circle device/account status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@circle-mcp What's the internet usage for each family profile this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
circle-mcp
MCP server exposing read-only Circle (Meetcircle/Aura) parental-control data: family profiles and per-profile internet usage. Runs over stdio (default) or streamable HTTP behind bearer keys (see HTTP / container).
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
Tool | Purpose |
| Family profiles (pid, name, mode, ageCategory, role, avatarUrl) |
| Usage summary for a profile (by pid or name): minutes/hours by category (Minecraft, Roblox, YouTube, ...) and by site, plus the deduplicated total. |
| Usage by category (games, social, video, ...) |
| Circle-wide status (name, mode, enabled, timezone, firmware) |
| Everything in one call; |
| Devices on the network with their owner ( |
| Circle Home units (cuuid, model, online/enabled, network, Wi-Fi, firmware); |
| Filter category catalog (id, name, mainCategory, description), to name the ids in usage reports |
| Child phones/tablets running the Circle app: counts plus each device's id, state, last check-in |
| Badges the Circle app shows per profile, |
| Usage by site for a profile (raw Circle report) |
| Allowed or blocked sites visited ( |
| Minutes left today per limited category (limit + today's extensions − used), paused / limits-on flags |
Profile writes (need CIRCLE_MCP_ALLOW_WRITES)
These change the Circle and are only registered when CIRCLE_MCP_ALLOW_WRITES
is 1/true/yes/on; with it unset the server stays read-only. Each returns
the raw Circle response as response plus an ok flag. None of the write tools
(here or in the sections below) has been run against the live API yet: the tests
stub HTTP, so treat the first live use of each as a test.
Tool | Purpose |
| Pause a profile's internet / go back to normal filtering |
| New profile ( |
| Change a profile's name |
|
|
| Turn time limits and/or off times |
| Delete a profile; needs |
| Move a device (by MAC) onto a profile |
| Per-category |
| Same for platforms (apps); merged unless |
| Drop one platform override |
| Always allow ( |
| Drop a site from the custom list |
| Bedtimes for every profile |
| Focus times (homework hours etc.) for every profile |
| Default filter sets for a new focus time |
| Replace a profile's daily time limits and weekend days |
| Extra minutes today in one category (keeps today's other rewards) |
| Move today's start/end of one off time (e.g. later bedtime tonight) |
| Replace a profile's legacy off-time windows |
| Create or replace a bedtime |
| Create, replace, or remove a focus time |
✏️ = changes settings on the Circle; registered only when | |
is | |
times are 24-hour | |
| Subscription plan, expiry, renewal and trial flags (needs username/password, not just an admin token) |
| Circle category id(s) for a domain or URL |
Write tools register only when | |
| |
Write tool | Purpose |
------------ | --------- |
| Rename a device ( |
| Cut / restore one device's internet |
| Remove a device from Circle (needs |
| Pause / resume the internet for the whole home |
| Circle's time zone (IANA id, validated) |
| Circle's language ( |
| Profile newly seen devices land in |
| Clear an active dashboard notification |
| Enable / disable a Circle Home unit ( |
| Toggle a Circle Home unit's compatible mode |
| Reboot a Circle Home unit (needs |
| Ask a child's phone to report its location; the answer goes to the parent app by push |
| Enrolled Circle Go child device: stage, ids, last ping, managed flag (Child-device mode) |
| Announce a new child device and request a pairing passcode |
| Approve the pending device from the parent account |
| Claim the device token and describe the device (home Wi-Fi) |
| Check in as the device; reports whether the parent still manages it |
| Download and unpack the device's rule bundle |
| Probe the four undocumented user-info endpoints (status + body each) |
✍️ = registered only when |
Related MCP server: mcp-nightscout
Setup
python3 -m venv .venv
.venv/bin/pip install -e .Tests (stubbed HTTP, no credentials needed):
.venv/bin/pip install -e '.[dev]' && .venv/bin/python -m pytestTests: .venv/bin/pip install -e '.[dev]' then .venv/bin/python -m pytest.
Configuration
Environment variables win; a secrets file fills the rest:
Env var | Secrets-file key | Purpose |
|
| Account email |
|
| Account password |
|
| Stable device identifier (any unique string) |
|
| Aura API client key ( |
|
| Optional pre-authenticated token (bypasses login) |
|
| Optional default profile for usage tools |
|
| Optional VC API host ( |
|
|
|
|
| Optional overrides of Circle's Cognito user pool and app client |
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.
HTTP / container
--transport streamable-http (or CIRCLE_MCP_TRANSPORT=streamable-http) serves MCP at
/mcp with stateless JSON responses, plus an unauthenticated GET /health.
Env var | Default | Purpose |
|
|
|
|
| Bind address ( |
| (none) | Comma list of accepted bearer keys, each |
| localhost only | Comma list of accepted |
|
| After Circle rejects the sign-in, refuse further sign-in attempts for this long (repeated bad logins could lock the account) |
Every request except /health needs Authorization: Bearer <key>; anything else gets 401.
Keys are compared in constant time; the id part only names the key in the startup log.
Circle failures (not configured, sign-in rejected, API errors) come back to the client as
tool errors with the reason; after a rejected sign-in /health also shows circle_auth_error.
The backoff applies to every transport.
Container (Containerfile: python:3.13-slim, non-root uid 10001, HEALTHCHECK on /health,
CIRCLE_SECRETS_FILE=/config/secrets.conf):
podman build --format docker -t localhost/circle-mcp:latest .
podman run -d --name circle-mcp --restart unless-stopped \
-e CIRCLE_MCP_KEYS="client1:$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')" \
-e CIRCLE_MCP_ALLOWED_HOSTS="localhost:8080,127.0.0.1:8080,myhost.example:3005" \
-p 3005:8080 -v /path/to/secrets.conf:/config/secrets.conf:ro,Z \
localhost/circle-mcp:latest--format docker matters: podman's default OCI format drops HEALTHCHECK. The secrets file
only needs the circle.* lines from Configuration.
Client registration (Claude Code .mcp.json or any streamable-HTTP client):
{"type": "http", "url": "http://myhost.example:3005/mcp",
"headers": {"Authorization": "Bearer <key>"}}Child-device mode
Besides the parent API, Circle has a separate API for managed phones and tablets
running the Circle app in Kid mode ("Circle Go", PROTOCOL.md Part C).
The go_* tools let this server enroll itself as such a device. That creates a
real device in the parent's Circle, so everything except go_device_status needs
CIRCLE_MCP_ALLOW_WRITES.
Enrollment:
go_enroll_start(device_name)announces the device and asks for a pairing passcode.The parent approves it:
go_enroll_approvedoes it with the parent account this server is configured for, or the parent types the passcode into their Circle app.go_enroll_finish(home_ssid)collects the device token and registers the device's home Wi-Fi name.go_device_statusshould then showstage: enrolled.
After that, go_ping checks in (managed: false means the parent removed the device),
go_download_settings fetches the rule bundle (three opaque binaries for Circle's filter
engine, not readable rules), and go_probe_user_info reports what the four declared but
unused user-info endpoints return. The device token renews itself on a 401; if the
renewal says management was turned off, device calls stop and the status says unmanaged.
Run go_enroll_start with replace=true to start over.
Env var | Default | Purpose |
|
| Device identity and tokens (written mode 0600; keep it private) |
|
| Where |
In a container, mount a writable volume for the state file, or the enrollment is lost on restart.
Deployment runbook
How to install, run, talk to, update and retire the HTTP server. Hostnames, ports and keys
below are examples; a private ops repo normally wraps these steps in a script (ours is
home-setup/scripts/install-circle-mcp-on-podman.sh, which reads the key and the circle.*
lines from a secrets repo and does everything in "Install" and "Update" idempotently).
Install (first time, on the container host)
Put the Circle credentials in a file the container can read,
circle.*lines only:circle.username = you@example.com circle.password = ... circle.device_id = circle-mcp circle.aura_public_key = circle_mobile_auth:...The container runs as uid 10001, so the file must be readable by that uid (
chown 10001 secrets.conf && chmod 0400 secrets.conf).Generate one bearer key per client:
python3 -c 'import secrets;print(secrets.token_urlsafe(32))'. Record it with the client's name in your secrets store; it is not recoverable from the server.Ship the source and build (from a checkout,
HEADor a tag):REV=$(git rev-parse --short HEAD) git archive --format=tar HEAD | ssh root@host "mkdir -p /root/circle-mcp-src-$REV && tar -x -C /root/circle-mcp-src-$REV" ssh root@host "cd /root/circle-mcp-src-$REV && podman build --format docker -t localhost/circle-mcp:$REV . && podman tag localhost/circle-mcp:$REV localhost/circle-mcp:latest"Run it (see HTTP / container for every env var).
CIRCLE_MCP_ALLOWED_HOSTSmust list everyHost:header a client will send, with and without the port, or the client gets HTTP 421. Open the port in the host firewall (firewall-cmd --add-port=3005/tcp --permanent).Check:
curl -s http://host:3005/health→{"status":"ok","circle_configured":true,"mcp_keys":1}.
Talk to it
# list tools (expect 4)
curl -s -X POST http://host:3005/mcp -H 'Authorization: Bearer <key>' \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# call one
curl -s -X POST http://host:3005/mcp -H 'Authorization: Bearer <key>' \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_profiles","arguments":{}}}'Responses are plain JSON (stateless; no session header needed). Register the server in a client as shown above; for a Hermes Agent gateway:
mcp_servers:
circle:
url: http://host:3005/mcp
headers:
Authorization: Bearer ${CIRCLE_MCP_KEY} # resolved from the gateway's env at connect time
tools: {resources: false, prompts: false}Read the logs and understand the errors
podman logs --tail 50 circle-mcp: one line per request plus the key id that authenticated.401 unauthorized: no or wrong bearer key.421 Misdirected Request: theHost:header is not inCIRCLE_MCP_ALLOWED_HOSTS. Both are the server, not Circle.A tool error
Cognito sign-in failed: NotAuthorizedExceptionis a wrong email or password.Aura sign-in failed: HTTP 401 {"message":"InvalidCredentials"}is Aura rejecting the account (the API key was accepted): either a wrong password, or a pre-Aura account that was forced toauth_method=auraand belongs on Cognito.NoCredentialmeans theaura_public_keyis wrong. After one rejection the server refuses to retry forCIRCLE_MCP_AUTH_BACKOFF_S(15 min) and/healthshowscircle_auth_error; fix the credentials file and restart the container to clear it. Repeated bad logins can lock the Circle account, so do not loop.
Update (new code or new credentials)
Rebuild with a new REV as in Install, then recreate the container with the same podman run
line (podman stop -t 10 circle-mcp && podman rm circle-mcp first). Keep the previous image tag
for rollback. Changing only secrets.conf or the env file needs just the stop/rm/run.
Rotate a bearer key
Generate a new key, replace it in CIRCLE_MCP_KEYS (several keys may be listed during the
switch), recreate the container, update the client, then drop the old key and recreate again.
Clients holding the old key get 401 immediately.
Retire
podman stop circle-mcp && podman rm circle-mcp, remove the firewall port, delete the secrets
file and the /root/circle-mcp-src-* directories, and revoke the keys in the clients.
API notes (2026-08)
The full endpoint catalog (parent and child-device surfaces, with MCP coverage) is in PROTOCOL.md. The notes below cover only what the server implements today.
Auth flow:
Get an identity JWT for the account. Circle has two sign-in backends and an account lives in exactly one of them:
Cognito (accounts from before the Aura migration): AWS Cognito
USER_SRP_AUTHagainst user poolus-west-2_TiQsgtChT, app clientfd7ail96985e3p3omb792ko0f(no client secret) →IdToken+RefreshToken. Implemented incognito.pywith the stdlib only.Aura:
POST https://api.aurasvc.io/auth/session/signinwith headerAuthorization: Public <aura_public_key>and body{"alias": <email>, "password": ...}→access_token+refresh_token(refresh via/auth/session/refresh_token)
auth_method=autotries Cognito first and falls back to Aura only when the pool reports the user as unknown (which is not a password failure, so the probe cannot lock the account). A Cognito-era account that is sent to Aura gets401 InvalidCredentialsno matter the password; that symptom means "wrong backend", not "wrong password".POST https://auth.meetcircle-blue.co/api/v2/grant/adminwith{"deviceid": <device_id>, "jwt": <id token or access token>}→ admin token andcircleidAfter each fresh grant,
GET https://register.meetcircle-blue.co/api/v1.0/host?circleid=<id>&token=<admin_token>; a non-emptyhostreplaces the default VC host. Any failure keeps the default (vc.meetcircle-blue.co);CIRCLE_VC_HOSTskips the lookup.Data endpoints on the VC host 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/all(profiles and status),/api/QUERY/devices,/api/QUERY/hardware,/api/QUERY/hardware/hardware/isOnline,/api/QUERY/categories,/api/v2/categories,/api/v2/profiles/badges/api/QUERY/users,/api/QUERY/circleinfo: fallbacks when/api/QUERY/allfails/api/v0.1/c/devStatus?gotoken=<admin_token>on port 8995 of the same host
Error semantics on signin:
401 {"message": "NoCredential"}— missing/invalidAuthorization: Public <key>header401 {"message": "InvalidCredentials"}— key accepted, username/password rejected
Available Tools
4 toolsget_circle_statusB
Get Circle device/account status.
Inputs: no named parameters.
get_usageB
Get detailed internet usage for a profile.
Args: profile_pid: Profile ID from list_profiles (falls back to configured profile_pid) day: Days ago to start (0 = today) ndays: Number of days to include
Inputs: day, ndays, profile_pid.
get_usage_categoriesA
Get internet usage broken down by category (e.g. games, social, video) for a profile.
Args: profile_pid: Profile ID from list_profiles (falls back to configured profile_pid) day: Days ago to start (0 = today) ndays: Number of days to include
Inputs: day, ndays, profile_pid.
list_profilesA
List Circle family profiles (pid, name, type). Use the pid with the usage tools.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The tools are mostly distinct: list_profiles is the discovery tool, get_usage provides raw usage, get_usage_categories provides categorized breakdown, and get_circle_status handles device health. get_usage and get_usage_categories could be confused at first, but their descriptions clearly separate raw totals from category breakdowns.
Tool names follow a consistent verb_noun pattern with snake_case: list_profiles, get_usage, get_usage_categories, get_circle_status. The only minor inconsistency is mixing list_ and get_ as the leading verb, but both clearly signal read operations.
Four tools is well-scoped for a focused read-only Circle internet usage server. Each tool covers a meaningful piece of functionality without unnecessary surface area.
The server provides profile discovery, raw usage lookup, category-level usage breakdown, and overall device status, which covers the main read-only workflows for a Circle usage monitor. Minor gaps such as per-device usage details or historical filtering beyond day/ndays could exist, but the core domain is well covered.
Maintenance
Related MCP Connectors
Read-only access to your Finch finances: accounts, transactions, spending, net worth, goals.
Read-only access to Cash Coach spending, goals, recurring payments, and transactions.
Understand your credit scores, reports, and next steps in plain English. Read-only access.
Read-only access to your bank, investment, and crypto accounts: balances, transactions, holdings.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceRead-only access to Stripe data including customers, charges, subscriptions, balance, and invoices.103 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables read-only access to a Nightscout instance for glucose readings, treatments, and deterministic server-side aggregates, allowing users to discuss their diabetes data with an AI assistant without write permissions.1MIT
- AlicenseAqualityBmaintenanceEnables read-only access to Klaviyo marketing data, including campaigns, flows, segments, metrics, reports, and customer profiles, across multiple Klaviyo accounts.2432 npmMIT
- AlicenseAqualityBmaintenanceEnables read-only access to Google Search Console data, including search analytics, sitemap status, URL inspection, and property listing.425 npmMIT