Circle MCP Server & CLI

What is the Circle MCP server & CLI?

The Circle MCP server & CLI is a free, open source program that lets AI agents work with community members, content, courses, events and workflows through the documented Admin API for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to Circle Admin API v2.

The CLI is the same program as commands. circle-cli list-spaces runs the same code your AI runs when you ask which community spaces your token can access, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Show this community’s spaces and recent posts.
Find the intended member before changing access.
Draft my community post and leave it unpublished.
Read that existing post ID before any publishing update.
Inspect course sections and lessons.
Show form submissions and the requested live-room transcript.
Read this workflow before the activation I requested.

Circle already has an official hosted MCP with broad Admin API coverage. This local package adds a shared task CLI, private named token settings, schema-derived commands and bounded page retrieval. No dedicated task CLI was identified in the official pages reviewed; that is a scoped finding, not proof of absence. Tool counts do not prove broader coverage or measured efficiency.

How to install the Circle MCP server

Choose your client in the existing install box. One npm package supplies MCP and CLI; GitHub Releases supplies the Claude Desktop archive. Configure private account access before a network request.

Set up private Circle access

Obtain an Admin V2 token

1. Sign in to the intended Circle community as an admin.
2. Open Settings > Developers > Tokens.
3. Create a token with type Admin V2 on an eligible plan.
4. Store it only in private shell/client settings as CIRCLE_API_TOKEN, or use the private file route below.
5. Run circle-cli doctor, then circle-cli doctor --network for a community read.

Follow the current quick start. Never use a Circle password, browser cookies, a member access token or a Google OAuth client as a substitute. The Admin API is intended for administrative integrations; member-facing experiences use the separate Headless APIs. The local package does not perform OAuth or host an authorization callback. login prints instructions without opening a browser or saving credentials.

Authentication discrepancy

The pinned OpenAPI security scheme specifies Authorization: Token AUTH_TOKEN; the quick-start prose and examples use Bearer. This version defaults to Token, preserving the schema and existing implementation. Explicitly set CIRCLE_AUTH_SCHEME=Bearer if your account requires the prose's scheme. Named accounts accept auth_scheme. No automatic auth fallback or write resubmission occurs. Both choices need live account validation; fixture checks establish only the outgoing request shape.

The token identifies the community. Requests use the fixed HTTPS origin app.circle.so, with its normal Host header. No arbitrary base URL or legacy community-ID override is exposed.

Private token file

Save only the token text in a regular file outside the checkout. Set CIRCLE_TOKEN_FILE to its absolute path. It takes precedence over the environment token, is limited to 64 KB, and refuses symlinks. Protect POSIX files with mode 0600 and Windows files/folders with user-only ACLs. The process caches the token in memory: restart after rotation. No automatic .env loader is included, and GUI clients may not inherit terminal variables.

Plans, usage and revocation

The official MCP is for admins on Business plans and above. Admin API allowances are Business 5,000; Enterprise/Circle Plus 30,000; Circle Plus Platform 250,000 requests/month. The documented rate limit is 2,000 requests per five minutes per IP and may change. Official MCP actions, local CLI calls, retries and every retrieved page consume the same community allowance. Many 4xx responses count too; usage may appear about five minutes later. Do not treat the old January 2025 enforcement paragraph as a current grace period.

Default local pacing is 200 ms per account/process; it is not a global quota manager. Other processes and tools share limits. Revoke a token through Circle and remove private client settings to disconnect. Uninstalling npm does not revoke access or delete community data.

Check that it works

Discovery and schemas work before authentication. The local doctor checks setup; the network doctor reads community details without printing private community content.

circle-cli --version
circle-cli doctor
circle-cli doctor --network
circle-cli list-spaces --per-page 5 --agent

A successful read proves only that endpoint’s access. It does not validate every action, plan feature or delivery outcome. Start with read-only when connecting a new client.

Use the Circle CLI

The CLI is the same 170 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_spaces runs as circle-cli list-spaces.

npm install -g @thenavidm/circle-mcp-cli@latest
circle-cli
circle-cli list-spaces --help
circle-cli schema create-post
circle-cli list-posts --space-id 7 --per-page 5 --agent

The bare circle-cli lists every command, and circle-cli <command> --help shows what a command takes. Every mutation needs --confirm for the requested action. --yes and --agent never replace it. Example IDs are illustrative; use resources discovered in your own community.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same server tools. MCP connects them directly to an AI chat; the CLI gives an agent with a terminal the same operations as commands.

The token comparison is pending. We measure four real Claude Code usage differences: every tool loaded, default tool search, the skill read once, and its recurring description line. Commands, help, selected schemas, results and reasoning also contribute to complete task cost.

There is no measured efficiency percentage for this version yet. Standing context and the total cost of a successful task will be reported separately.

Community workflows

Draft, inspect, then publish only when requested

Discover the intended basic space first. A basic post requires space_id and name; content uses tiptap_body and a nested Tiptap document rather than an invented plain body field. These illustrative IDs must be replaced with real discovered IDs:

circle-cli list-spaces --per-page 5 --agent
circle-cli create-post --space-id 7 --name "Community notes" --tiptap-body '{"body":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Your actual post content."}]}]}}' --confirm --agent
circle-cli get-post --post-id 19 --agent

The wrapper defaults basic/image post creation to draft. Read that same post ID and inspect it in Circle. A later publishing/scheduling update needs the user's specific request and explicit status/confirmation. Review skip_notifications, timestamps and audience carefully. Do not overwrite a branded or complex document with a sample paragraph. See Tiptap concepts and rich text.

Members, invitations and messages

Search/read the intended member before access changes. create_member invites a member unless the supplied supported fields change that behavior; skip_invitation can suppress an invitation. Use documented member IDs, emails, access-group IDs and tags, not a user's password in a model prompt. remove_member deactivates a membership; delete_community_member is a distinct deletion operation. Read schemas before choosing one.

send_message uses rich_text_body and exactly one recipient route (user_email, user_emails or chat_room_uuid) per the pinned body union. Publishing, comments, messages, invitations, event reminders and workflow activation can contact people. Guard confirmation does not establish consent or successful delivery. Only perform the requested operation.

Events, courses and workflows

Events use a nested event object with event settings, location and reminder options, plus the operation's space input. Courses use current section/lesson IDs and documented bodies; progress updates have their own fields. Workflows use UUIDs, not the numeric IDs used by many other endpoints. Read and inspect the current workflow before confirmed activation. Deactivation, duplication and billing/subscription actions have different effects; tool availability never substitutes for the intended task.

Pagination, exports and uploads

Bounded pages

The 33 reviewed paginated reads use native page and per_page; no cursor is invented. all_pages starts at the requested page or page 1, keeps page size fixed, stops at max_items (default 1,000, maximum 10,000) or 100 requests, and refuses empty/repeated continuing pages. The local per_page cap is 100. Responses retain the provider's records/metadata and add collected/pages/truncated/resume.

circle-cli list-members --per-page 25 --agent
circle-cli list-members --all-pages --max-items 500 --per-page 25 --agent

When a cap cuts through a page, resume contains that page, the fixed per_page and the count to skip after retrieving it again. When a full page is consumed, resume points to the next page with skip 0. Preserve the same query/filter/sort and do not change page size: doing so changes offset boundaries. This is not a consistent snapshot; concurrent community changes can shift records. The helper returns continuation state but does not offer an invented --skip API argument. One bounded result is not a complete backup guarantee.

Exports and quota

Export tools are confirmed writes that may enqueue jobs or return download links; acceptance is not proof of completion. Preserve returned IDs/status and follow the documented account workflow. Keep membership/billing data and download URLs private. Every page/retry consumes allowance; a long Retry-After is surfaced instead of shortened into an early retry.

File metadata and direct uploads

create_direct_upload creates the documented upload metadata/slot using blob key, filename, MIME type, byte_size and a Base64 MD5 checksum. It does not read a local file or complete the storage PUT for you. Follow the upload protocol: create metadata, upload the exact intended file to the returned signed storage URL with its returned headers, then use the returned signed_id where the content schema accepts it. The provider concept page illustrates Member API; this package uses the pinned Admin v2 direct_uploads route.

Never send the Admin token to the storage URL, expose private signed URLs in public output, or treat a slot as a completed upload. Embeds/SGIDs, basic-post covers, image galleries, lesson media and member avatars use different schema fields. This package does not host an uploader or webhook receiver; no incomplete file workflow is advertised as automatic.

Every Circle tool

Actual discovery supplies all 170 tools below: 66 reads and 104 confirmed writes. The full argument tables and circle-cli schema expose required IDs, body fields and native page controls. This package covers the pinned Admin v2 operations, not the separate Member API or every Circle UI workflow.

Access group members

Access groups

Advanced search

Chat preferences

Chat room message imports

Comments

Communities

Community leads

Community member charges

Community member spaces

Community member subscriptions

Community member access groups

Community members

Community segments

Contact notes

Course lesson progress

Course lessons

Course sections

Direct uploads

Embeds

Event attendees

Events

Filter kit configuration

Filter kit controls

Flagged contents

Forms

Gamification

Posts

Invitation links

Live

Locations

Member tags

Messages

Page profile fields

Payment method settings

Paywall affiliate payouts

Paywall affiliates

Paywall coupons

Paywall groups

Paywalls

Post followers

Profile fields

Connect settings

Space group members

Space groups

Space members

Spaces

Tagged members

Tax settings

Topics

Workflows

Accounts

Is the Circle MCP server safe?

All 104 mutations require explicit confirmation. Read-only hides them and refuses direct calls, leaving 66 reads. CIRCLE_ALLOW_DESTRUCTIVE=0 also blocks all writes even when confirmed.

Messages, invitations, notifications, access changes, billing and workflow activation have different effects. Review the exact account and operation. Writes never retry automatically; inspect account state after an unknown outcome before repeating one.

Make it read-only

Privately set CIRCLE_READ_ONLY=1, restart or reconnect and check discovery. Remove or disable it only when requested writes are needed. Every write still requires its own confirmation.

Keep a log of every write

Set CIRCLE_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Authorized API requests go directly to https://app.circle.so/api/admin/v2; redirects are refused. No Navid-hosted relay, analytics or telemetry is included. Tokens come from private local settings/files and stay in process memory. Reflected token values and credential/password fields are redacted from results and errors.

Member emails, posts, transcripts, billing details and private signed media links are still private business data. Secret redaction does not anonymize them. Your AI client and Circle apply their own retention/sharing rules. --select filters local output after receipt. Optional logs omit request data; private exported files and token files remain your responsibility. No source, npm tarball or desktop archive may include real credentials or private account instructions. Report vulnerabilities privately via SECURITY.md.

Several private accounts

Use private CIRCLE_ACCOUNTS JSON instead of single-account variables:

[{"name":"work","api_token":"YOUR_WORK_ADMIN_TOKEN","auth_scheme":"Token"},{"name":"personal","token_file":"/absolute/private/path/circle-token.txt","auth_scheme":"Bearer"}]

Set CIRCLE_DEFAULT_ACCOUNT=work. Labels must be unique. --account chooses credentials; the token identifies the community. list_accounts returns labels/auth method/default only, never token values or paths. Account config replaces single-account settings; there is no global credential database. Separate processes remain preferable when strict isolation matters.

circle-cli list-accounts --agent
circle-cli list-spaces --account work --per-page 5 --agent
circle-cli get-community --account personal --agent

Circle MCP server settings

Use private local shell or user-client settings. GUI processes may not inherit terminal variables. This package has no automatic .env loader. Account labels select credentials; tokens identify communities.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Complete client, OS and desktop setup

Put actual values only into private user settings. INSTALL.md ships in npm and provides the same complete setup. Browser-only clients use Circle’s official hosted MCP.

Claude Code

For a user-scoped connection, after privately configuring credentials:

claude mcp add --scope user circle -- npx -y @thenavidm/circle-mcp-cli@latest
claude mcp list

Use the client's private local environment settings for the account variable if they are not inherited. Claude's -e NAME=value registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.

Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.

Codex

codex mcp add circle -- npx -y @thenavidm/circle-mcp-cli@latest
codex mcp list

Account credentials must reach the server through private environment settings. codex mcp add --env NAME=value stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:

[mcp_servers.circle]
command = "npx"
args = ["-y", "@thenavidm/circle-mcp-cli@latest"]
env_vars = ["CIRCLE_API_TOKEN", "CIRCLE_TOKEN_FILE", "CIRCLE_AUTH_SCHEME"]

env_vars forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and --agent output.

Claude Desktop

Install the .mcpb extension

1. Download circle-2.0.0.mcpb from GitHub Releases.
2. In a supported Claude Desktop build, open Settings > Extensions > Advanced settings > Install Extension… and select it.
3. Enter a private Admin token in the sensitive setting, or an absolute private token-file path. Leave the unused method empty. Set the authentication scheme to Token by default, or explicitly choose Bearer if your account requires the quick-start scheme described above.
4. Enable read-only if you want only the 66 reads. Reconnect and ask for account verification.

The bundle includes production dependencies and no credentials. Use a regular private token-only file if you prefer file-based credentials. The manifest requires Node 22 or newer from a compatible host. Organization policy may restrict custom extensions. Manual bundle updates require installing the new version; no automatic directory updates are promised. GUI installation remains unverified separately from archive/protocol checks.

Manual config

Open Settings > Developer > Edit Config, or use your platform's config file:

{
  "mcpServers": {
    "circle": {
      "command": "npx",
      "args": ["-y", "@thenavidm/circle-mcp-cli@latest"],
      "env": {
        "CIRCLE_API_TOKEN": "YOUR_PRIVATE_ADMIN_TOKEN",
        "CIRCLE_TOKEN_FILE": "",
        "CIRCLE_AUTH_SCHEME": "Token"
      }
    }
  }
}

Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.

If a Windows launcher cannot execute npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@thenavidm/circle-mcp-cli@latest"]. An absolute node executable and installed dist/index.js path also avoids launcher/PATH problems.

Cursor

Use private user settings at ~/.cursor/mcp.json, or Settings > Tools & MCP. Cursor documents environment interpolation and envFile support.

{
  "mcpServers": {
    "circle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/circle-mcp-cli@latest"],
      "env": {
        "CIRCLE_API_TOKEN": "${env:CIRCLE_API_TOKEN}",
        "CIRCLE_TOKEN_FILE": "${env:CIRCLE_TOKEN_FILE}",
        "CIRCLE_AUTH_SCHEME": "${env:CIRCLE_AUTH_SCHEME}"
      }
    }
  }
}

The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project's .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.

VS Code and Copilot

Use MCP: Open User Configuration. VS Code uses servers and secure inputs, rather than a mcpServers root:

{
  "inputs": [
    {"type": "promptString", "id": "circle-api-key", "description": "Circle Admin token (leave empty for a private token file)", "password": true},
    {"type": "promptString", "id": "circle-token-file", "description": "Optional private token-file path (leave empty for Admin token)"}
  ],
  "servers": {
    "circle": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/circle-mcp-cli@latest"],
      "env": {
        "CIRCLE_API_TOKEN": "${input:circle-api-key}",
        "CIRCLE_TOKEN_FILE": "${input:circle-token-file}",
        "CIRCLE_AUTH_SCHEME": "Token"
      }
    }
  }
}

Start Circle through the MCP controls, approve trust if prompted, and enter credentials in the private input prompts. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.

Windsurf

Open Cascade's MCP settings or edit the private user file ~/.codeium/windsurf/mcp_config.json. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See Windsurf's current MCP documentation. Restart or reconnect Circle in Cascade; project files must not contain secrets.

Zed

Open Settings > AI > MCP Servers > Add Server > Add Local Server, or your user settings file. Zed uses context_servers:

{
  "context_servers": {
    "circle": {
      "command": "npx",
      "args": ["-y", "@thenavidm/circle-mcp-cli@latest"],
      "env": {
        "CIRCLE_API_TOKEN": "YOUR_PRIVATE_ADMIN_TOKEN",
        "CIRCLE_TOKEN_FILE": "",
        "CIRCLE_AUTH_SCHEME": "Token"
      }
    }
  }
}

Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.

Gemini CLI

Merge the Claude Desktop manual mcpServers block into your private ~/.gemini/settings.json. Configure the three env values locally, then restart Gemini CLI and inspect /mcp. See Gemini CLI's MCP configuration. Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.

Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.

Docker

Build locally from the reviewed source; no prebuilt registry image is claimed:

git clone https://github.com/thenavidm/circle-mcp-cli.git
cd circle-mcp-cli
docker build -t circle-mcp-cli .
docker run --rm -i -e CIRCLE_API_TOKEN circle-mcp-cli

-e CIRCLE_API_TOKEN forwards the shell's already configured private value. MCP needs -i and stdio. For file-based tokens, mount the private token file read-only and set the absolute in-container CIRCLE_TOKEN_FILE path. Host paths do not automatically exist inside a container. Forward CIRCLE_AUTH_SCHEME when explicitly configured. This package never refreshes or rewrites tokens; restart after rotation.

Cline and other local MCP clients

Use the client's Add MCP server flow with command npx, arguments -y and @thenavidm/circle-mcp-cli@latest, stdio transport, and private local CIRCLE_API_TOKEN or CIRCLE_TOKEN_FILE settings. UI names depend on the installed client. Reconnect and discover tools before an account call. Browser-only clients need a remote HTTPS connector; use Circle's official server rather than this local stdio command.

Command inputs, JSON and output

Tool names become dashed commands; underscores are accepted too. Path parameter names follow the discovered schema, such as post_id → --post-id. Body tools accept individual top-level flags, complete --payload JSON, or --payload-file pointing to a regular JSON body file up to 5 MB. Do not mix those body routes. Path/query flags remain separate. Nested objects take JSON and array flags repeat once per item; a whole array is not a single item.

circle-cli get-post --help
circle-cli schema create-post
circle-cli list-members --member-tag-ids 3 --member-tag-ids 4 --per-page 10 --agent
circle-cli search --query "onboarding" --filters '{"space_ids":["7"]}' --agent

IDs above are illustrative; use discovered resources from your own community. Nullable fields require an actual JSON null inside payload; --field null is a string. Nested Tiptap properties preserve upstream extensibility; unknown top-level body fields are refused. Body-required fields are validated during execution even when the wrapper schema allows an alternative payload route. Operations whose upstream request body is required need body flags or an explicit payload; a deliberately supplied empty object is sent as JSON, never omitted.

Results go to stdout, errors as JSON to stderr. Selection changes local output, not the original API response or quota charge. API success is not proof of notification delivery or a completed export.

Official MCP and community comparisons

No dedicated Circle-published task CLI was identified in the official developer/MCP pages reviewed on October 2, 2026. This is a scoped finding, not proof of absence. Claude Code setup commands in MCP docs are MCP registration, not a Circle administration CLI. Neither our operation count nor a community README count proves broader capability, reliability or token savings. This release does not provide the separate Member API or Google authentication.

Current primary references: Admin API, quick start, limits, official OpenAPI, official MCP. See COMPARISON.md for review scope and pending evidence.

Versions and migration

The OpenAPI document calls its info version v1 while the routes are Admin v2. Provenance records both; do not rename the API based on that info field. Original upstream SHA-256: 9bdd6e72611fe2af43e308ffadb9e9a64b0aa5d5763004839ac3b70de335f5a0. The public pinned snapshot removes one credential-like upload-key example; its SHA-256 is 3e6478f0ac859789a70b8356ac0c91901de99134f637832809497d555e897241. Examples are excluded from generated validation.

Many documented legacy names remain where current operations exist. Arguments and routes need migration: posts use /posts with space_id input, comments use /comments with post_id input, memberships and attendees use current top-level resources, and workflows require UUIDs. Unsupported v1-only like/unlike helpers are omitted. CIRCLE_COMMUNITY_ID is no longer used. Legacy HTML/body shortcuts are not silently converted to Tiptap. See CHANGELOG.md for the exact legacy-name migration table. Preserve the existing AGPL license.

Build/typecheck, 25 fixture/shared-CLI checks and real local discovery are verified. These checks cover every write guard, nested body validation, pagination, auth header shape, retry policy, secret redaction and actual CLI exit codes. Public release/artifact/CI evidence is recorded after publication. Live provider outcomes, desktop GUI installation and fresh model usage benchmarks remain pending.

Updates and removal

npm install -g @thenavidm/circle-mcp-cli@latest
circle-cli --version
claude mcp remove --scope user circle
codex mcp remove circle
npm uninstall -g @thenavidm/circle-mcp-cli

Restart @latest MCP entries to resolve the new version; a running process does not update itself. Pin a reviewed version for reproducible automation. Read CHANGELOG.md and GitHub Releases before major updates. Manually installed desktop extensions need the new versioned .mcpb installed separately. No directory-driven automatic desktop update is claimed.

Remove each manual client entry and copied skill as appropriate. Uninstalling does not revoke tokens, delete community content, undo invitations or cancel workflows. Revoke tokens in Circle separately. Preserve private data before removing local private files. Do not overwrite an existing npm version to roll back.

Validation and remaining evidence

Build, typecheck and 25 behavior/shared-CLI checks pass. Real local discovery reports 170 tools and 66 in read-only mode. Every one of the 104 writes is guard-checked. The production dependency audit has zero findings; the development-only MCPB/node-forge advisory is documented in SECURITY.md and excluded from the desktop archive.

The exact source history, npm package and desktop archive are scanned for secrets. Public CI, public installation and downloaded desktop discovery are recorded after release. Live account outcomes, desktop GUI installation and fresh matched model usage/task measurements remain pending. No measured superiority claim is invented.