# Circle MCP Server

Operate and audit your Circle.so community from Claude with tools for spaces, posts, members, comments, health snapshots, and controlled content actions.

## Quick Start

```bash
# Connect this server (installs CLI if needed)
npx -y @smithery/cli@latest mcp add iamnortey/circle-so-mcp

# Browse available tools
npx -y @smithery/cli@latest tool list iamnortey/circle-so-mcp

# Get full schema for a tool
npx -y @smithery/cli@latest tool get iamnortey/circle-so-mcp circle_list_spaces

# Call a tool
npx -y @smithery/cli@latest tool call iamnortey/circle-so-mcp circle_list_spaces '{}'
```

## Direct MCP Connection

Endpoint: `https://circle-so-mcp--iamnortey.run.tools`

**Required config:**
- `circleApiToken` (query) — Circle.so Admin API token (v2). Required. Obtain from Circle Admin > Settings > API.

**Optional config:**
- `circleBaseUrl` (query) — Circle API base URL. Override only for custom or proxy deployments.

## Tools (16)

- `circle_list_spaces` — List spaces in the Circle community. Returns paginated results with space details including name, type, URL, and settin…
- `circle_get_space` — Retrieve a single Circle space by its numeric ID. Returns full space details including name, type, URL, visibility sett…
- `circle_list_posts` — List posts in the Circle community. Returns paginated results with full post details including title, content (HTML and…
- `circle_get_post` — Retrieve a single Circle post by its numeric ID. Returns full post details including title, HTML body, structured TipTa…
- `circle_list_members` — List community members in Circle. Returns paginated results with member details including name, email, profile URL, act…
- `circle_search` — Search across the Circle community. Returns lightweight summary objects with id, name, slug, and type. Results are NOT …
- `circle_list_comments` — List comments in the Circle community. Filter by post_id to get comments on a specific post, or by space_id to get comm…
- `circle_get_comment` — Retrieve a single Circle comment by its numeric ID. Returns full comment details including body text, author info, and …
- `circle_list_topics` — List all topics (tags/categories) in the Circle community. Topics are used to categorize posts. Returns paginated resul…
- `circle_get_community` — Retrieve community-level metadata for the connected Circle community. Returns the community name, URL, slug, branding i…
- `circle_list_space_groups` — List space groups in the Circle community. Space groups organize spaces into navigational categories (e.g., 'Getting St…
- `circle_detect_unanswered_posts` — Detect posts with zero comments — potential unanswered questions or unengaged content. Fetches published posts from the…
- `circle_community_health` — Generate a community health snapshot by aggregating data from multiple Circle API endpoints. Fetches community info, sp…
- `circle_create_post` — Create a new post in a Circle space. Requires space_id (use circle_list_spaces to find IDs), a title (name), and HTML b…
- `circle_update_post` — Update an existing Circle post. Requires post_id (use circle_list_posts or circle_get_post to find IDs). Only provided …
- `circle_create_comment` — Create a comment on a Circle post. Requires post_id (use circle_list_posts or circle_get_post to find IDs) and HTML bod…

```bash
# Get full input/output schema for a tool
npx -y @smithery/cli@latest tool get iamnortey/circle-so-mcp <tool-name>
```