circle-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CIRCLE_VC_HOST | No | Optional VC API host (vc.example.com or a full https:// URL). Skips the per-circle host lookup. Can also be provided as circle.vc_host in the secrets file. | |
| CIRCLE_MCP_HOST | No | HTTP bind address. Equivalent to --host. | 0.0.0.0 |
| CIRCLE_MCP_KEYS | No | Comma list of accepted bearer keys, each key or id:key. Required for the streamable-http transport; the HTTP server refuses to start without it. | |
| CIRCLE_MCP_PORT | No | HTTP bind port. Equivalent to --port. | 8080 |
| CIRCLE_PASSWORD | No | Account password. Can also be provided as circle.password in the secrets file. | |
| CIRCLE_USERNAME | No | Account email. Can also be provided as circle.username in the secrets file. | |
| CIRCLE_DEVICE_ID | No | Stable device identifier (any unique string). Can also be provided as circle.device_id in the secrets file. | |
| CIRCLE_ADMIN_TOKEN | No | Optional pre-authenticated admin token that bypasses login. Can also be provided as circle.admin_token in the secrets file. | |
| CIRCLE_AUTH_METHOD | No | Which sign-in backend holds the account: auto, aura, or cognito. Can also be provided as circle.auth_method in the secrets file. | auto |
| CIRCLE_PROFILE_PID | No | Optional default profile pid for usage tools. Can also be provided as circle.profile_pid in the secrets file. | |
| CIRCLE_SECRETS_FILE | No | Path to a conf file with circle.<key> = <value> lines, keeping credentials out of the MCP client config. | |
| CIRCLE_GO_STATE_FILE | No | Where child-device identity and tokens are stored (written mode 0600). Keep it private. | ~/.circle-mcp/go-device.json |
| CIRCLE_MCP_TRANSPORT | No | stdio or streamable-http. Equivalent to --transport. | stdio |
| CIRCLE_AURA_PUBLIC_KEY | No | Aura API client key, e.g. circle_mobile_auth:... Can also be provided as circle.aura_public_key in the secrets file. | |
| CIRCLE_COGNITO_POOL_ID | No | Optional override of Circle's Cognito user pool. Can also be provided as circle.cognito_pool_id in the secrets file. | |
| CIRCLE_GO_SETTINGS_DIR | No | Directory where go_download_settings writes the downloaded bundle, next to the state file by default. | go-settings/ |
| CIRCLE_MCP_ALLOW_WRITES | No | Set to 1, true, yes, or on to register Circle-changing write tools. Default unset leaves the server read-only. | |
| CIRCLE_COGNITO_CLIENT_ID | No | Optional override of Circle's Cognito app client. Can also be provided as circle.cognito_client_id in the secrets file. | |
| CIRCLE_MCP_ALLOWED_HOSTS | No | Comma list of accepted Host headers for DNS-rebinding protection. Defaults to localhost only; * turns the check off. | |
| CIRCLE_MCP_AUTH_BACKOFF_S | No | After Circle rejects sign-in, refuse further sign-in attempts for this many seconds. | 900 |
| CIRCLE_MCP_AUTH_RETRY_DELAY | No | Deprecated placeholder; use CIRCLE_MCP_AUTH_BACKOFF_SECONDS. | |
| CIRCLE_MCP_AUTH_BACKOFF_SECONDS | No | Delay in seconds before retrying a rejected Circle sign-in. Default 900. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_profilesA | List Circle family profiles (pid, name, type). Use the pid with the usage tools. |
| 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 |
| 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 |
| get_circle_statusB | Get Circle device/account status. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.