Circle.so MCP Server

A Model Context Protocol (MCP) server that provides full access to the Circle.so Admin API V1. Manage your Circle.so community — spaces, members, posts, events, courses, and more — directly from any MCP-compatible client like Claude Code, Claude Desktop, or your own agent.

71 tools covering every major API surface. 10 built-in prompts for common community management workflows.

Quick Start

Run with npx (no install required)

CIRCLE_SO_API_KEY=your_api_key npx @alludium/circle-so-mcp-server

Add to Claude Code

claude mcp add circle-so -- npx @alludium/circle-so-mcp-server

Then set your API key in the MCP server config at ~/.claude.json:

{
  "mcpServers": {
    "circle-so": {
      "type": "stdio",
      "command": "npx",
      "args": ["@alludium/circle-so-mcp-server"],
      "env": {
        "CIRCLE_SO_API_KEY": "your_api_key"
      }
    }
  }
}

Add to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "circle-so": {
      "command": "npx",
      "args": ["@alludium/circle-so-mcp-server"],
      "env": {
        "CIRCLE_SO_API_KEY": "your_api_key"
      }
    }
  }
}

Build from source

git clone https://github.com/alludium/circle-so-mcp-server.git
cd circle-so-mcp-server
npm install
npm run build
CIRCLE_SO_API_KEY=your_api_key npm start

Getting Your API Key

1. Log in to your Circle.so admin dashboard
2. Go to Settings → API
3. Generate an Admin API V1 token
4. Set it as CIRCLE_SO_API_KEY in your environment or MCP config

Note: This server uses the Circle.so Admin API V1. V2 tokens are not compatible.

Tools (71)

Community (2)

| Tool | Description | |------|-------------| | circle_get_community | Get community details, settings, and configuration | | circle_update_community | Update community name and privacy settings |

Spaces (5)

| Tool | Description | |------|-------------| | circle_list_spaces | List all spaces with sorting and pagination | | circle_get_space | Get space details by ID | | circle_create_space | Create a new space in a space group | | circle_update_space | Update space settings (name, visibility, display) | | circle_delete_space | Delete a space |

Space Groups (5)

| Tool | Description | |------|-------------| | circle_list_space_groups | List all space groups | | circle_get_space_group | Get space group details | | circle_create_space_group | Create a new space group | | circle_update_space_group | Update space group settings | | circle_delete_space_group | Delete a space group |

Members (7)

| Tool | Description | |------|-------------| | circle_list_members | List members with filters and pagination | | circle_get_member | Get member profile by ID | | circle_search_member | Search members by email | | circle_create_member | Invite or add a new member | | circle_update_member | Update member profile and role | | circle_deactivate_member | Deactivate a member account | | circle_list_member_spaces | List spaces a member belongs to |

Posts (5)

| Tool | Description | |------|-------------| | circle_list_posts | List posts with filters by space, status, search | | circle_get_post | Get post details by ID | | circle_create_post | Create a post with HTML body content | | circle_update_post | Update post title, status, and metadata | | circle_delete_post | Delete a post |

Comments (4)

| Tool | Description | |------|-------------| | circle_list_comments | List comments on a post | | circle_get_comment | Get comment details | | circle_create_comment | Add a comment to a post | | circle_delete_comment | Delete a comment |

Events (8)

| Tool | Description | |------|-------------| | circle_list_events | List events with filters | | circle_get_event | Get event details | | circle_create_event | Create a new event | | circle_update_event | Update event details | | circle_delete_event | Delete an event | | circle_list_event_attendees | List event attendees | | circle_add_event_attendee | Add an attendee to an event | | circle_remove_event_attendee | Remove an attendee |

Courses (10)

| Tool | Description | |------|-------------| | circle_list_course_sections | List sections in a course space | | circle_get_course_section | Get section details | | circle_create_course_section | Create a course section | | circle_update_course_section | Update a course section | | circle_delete_course_section | Delete a course section | | circle_list_course_lessons | List lessons in a section | | circle_get_course_lesson | Get lesson details | | circle_create_course_lesson | Create a lesson | | circle_update_course_lesson | Update a lesson | | circle_delete_course_lesson | Delete a lesson |

Member Tags (7)

| Tool | Description | |------|-------------| | circle_list_member_tags | List all member tags | | circle_get_member_tag | Get tag details | | circle_create_member_tag | Create a new tag | | circle_update_member_tag | Update a tag | | circle_delete_member_tag | Delete a tag | | circle_tag_member | Apply a tag to a member | | circle_untag_member | Remove a tag from a member |

Space Members (4)

| Tool | Description | |------|-------------| | circle_list_space_members | List members of a space | | circle_get_space_member | Get space membership details | | circle_add_space_member | Add a member to a space | | circle_remove_space_member | Remove a member from a space |

Topics (5)

| Tool | Description | |------|-------------| | circle_list_topics | List topics in a space | | circle_get_topic | Get topic details | | circle_create_topic | Create a new topic | | circle_update_topic | Update a topic | | circle_delete_topic | Delete a topic |

Access Groups (8)

| Tool | Description | |------|-------------| | circle_list_access_groups | List all access groups | | circle_get_access_group | Get access group details | | circle_create_access_group | Create an access group | | circle_update_access_group | Update an access group | | circle_archive_access_group | Archive an access group | | circle_unarchive_access_group | Unarchive an access group | | circle_list_access_group_members | List members in an access group | | circle_add_access_group_member | Add a member to an access group |

Moderation (1)

| Tool | Description | |------|-------------| | circle_list_flagged_content | List content flagged for moderation |

Prompts (10)

Built-in prompt templates for common community management workflows. Use these from any MCP client that supports prompts.

| Prompt | Description | Arguments | |--------|-------------|-----------| | community_health_check | Assess community health — spaces, members, activity, flagged content | — | | welcome_new_member | Draft a personalised welcome for a new member | member_email | | draft_announcement | Create a structured announcement post | topic, space_name? | | plan_content_calendar | Generate a multi-week content plan across spaces | weeks?, focus? | | onboard_community | Set up a new community from scratch with guided structure | community_type, name | | moderate_flagged_content | Review and action flagged content as a moderation queue | — | | plan_event | Plan and create a community event | event_idea, date? | | create_space | Design a new space with topics and welcome post | purpose | | design_course | Build a course with sections and lessons | course_topic, lesson_count? | | manage_access_groups | Review and manage member access tiers | goal? |

API Notes

This server targets the Circle.so Admin API V1 (https://app.circle.so/api/v1).

Key things to know:

• Authentication: Uses Token header auth (not Bearer). The server handles this automatically.
• Community ID: Auto-discovered on startup from your API token. Injected into every request.
• Post bodies: Use HTML strings in the body parameter. Circle wraps content in a <div> automatically.
• Post body on update: The V1 API does not support updating post body content via PUT. To change post content, delete and recreate.
• Space types: Creating spaces with space_type of "event" or "course" may default to "basic" in V1. Configure space types via the Circle.so dashboard.
• Rate limits: The server uses a 30-second timeout per request. Circle.so may impose its own rate limits.

Project Structure

src/
├── index.ts              # Entry point, server setup
├── constants.ts          # API base URL, limits
├── prompts.ts            # 10 MCP prompt templates
├── schemas/
│   └── common.ts         # Shared Zod schemas (pagination)
├── services/
│   └── api-client.ts     # HTTP client, auth, community ID
└── tools/
    ├── access-groups.ts  # Access group management (8 tools)
    ├── comments.ts       # Comment CRUD (4 tools)
    ├── community.ts      # Community get/update (2 tools)
    ├── courses.ts        # Course sections & lessons (10 tools)
    ├── events.ts         # Event CRUD + attendees (8 tools)
    ├── member-tags.ts    # Tag CRUD + tagging (7 tools)
    ├── members.ts        # Member management (7 tools)
    ├── misc.ts           # Flagged content (1 tool)
    ├── posts.ts          # Post CRUD (5 tools)
    ├── space-groups.ts   # Space group CRUD (5 tools)
    ├── space-members.ts  # Space membership (4 tools)
    ├── spaces.ts         # Space CRUD (5 tools)
    └── topics.ts         # Topic CRUD (5 tools)

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode (auto-reload)
npm run dev

# Clean build output
npm run clean

License

MIT

Built with the Model Context Protocol TypeScript SDK.