{"_id":"@alludium/circle-so-mcp-server","name":"@alludium/circle-so-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alludium/circle-so-mcp-server","version":"1.0.0","description":"MCP server for Circle.so Admin API — 71 tools and 10 prompts for community management","type":"module","main":"dist/index.js","bin":{"circle-so-mcp-server":"dist/index.js"},"scripts":{"start":"node dist/index.js","dev":"tsx watch src/index.ts","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","circle","circle-so","community","admin-api","ai","llm","claude"],"author":{"name":"Alludium"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/alludium/circle-so-mcp-server.git"},"homepage":"https://github.com/alludium/circle-so-mcp-server#readme","bugs":{"url":"https://github.com/alludium/circle-so-mcp-server/issues"},"engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.6.1","axios":"^1.7.9","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.10.0","tsx":"^4.19.2","typescript":"^5.7.2"},"_id":"@alludium/circle-so-mcp-server@1.0.0","gitHead":"238c7954fe2c5046708f96e9cfe7c6a4f5330392","types":"./dist/index.d.ts","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ubBwRsAHCP/3ZE83BxyejnSB1RCSu7rGNIfr1MgjOkXChDoj99V97ZD4inaLowJNReRZv7ShWRDzQDPhMpONEA==","shasum":"1f1a4bee2b98cbeed367a86dc1b82921360f6331","tarball":"https://registry.npmjs.org/@alludium/circle-so-mcp-server/-/circle-so-mcp-server-1.0.0.tgz","fileCount":75,"unpackedSize":191364,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEVWxtk/aBm0XAHh5hd8veavtRAYuc4d0lvv618YOx5eAiEA03Jv7H1o7E7BPgASd4cyMQ7R5nmWy2UUYYsonSRv7wA="}]},"_npmUser":{"name":"john-alludium","email":"john@alludium.ai"},"directories":{},"maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"},{"name":"john-alludium","email":"john@alludium.ai"},{"name":"jubernunes","email":"juber@alludium.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/circle-so-mcp-server_1.0.0_1773240295315_0.7462193381715156"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T14:44:55.195Z","1.0.0":"2026-03-11T14:44:55.463Z","modified":"2026-03-11T14:44:55.753Z"},"maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"},{"name":"john-alludium","email":"john@alludium.ai"},{"name":"jubernunes","email":"juber@alludium.ai"}],"description":"MCP server for Circle.so Admin API — 71 tools and 10 prompts for community management","homepage":"https://github.com/alludium/circle-so-mcp-server#readme","keywords":["mcp","model-context-protocol","circle","circle-so","community","admin-api","ai","llm","claude"],"repository":{"type":"git","url":"git+https://github.com/alludium/circle-so-mcp-server.git"},"author":{"name":"Alludium"},"bugs":{"url":"https://github.com/alludium/circle-so-mcp-server/issues"},"license":"MIT","readme":"# Circle.so MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides full access to the [Circle.so Admin API V1](https://api.circle.so/apis/admin-api). Manage your Circle.so community — spaces, members, posts, events, courses, and more — directly from any MCP-compatible client like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Claude Desktop](https://claude.ai/download), or your own agent.\n\n**71 tools** covering every major API surface. **10 built-in prompts** for common community management workflows.\n\n---\n\n## Quick Start\n\n### Run with npx (no install required)\n\n```bash\nCIRCLE_SO_API_KEY=your_api_key npx @alludium/circle-so-mcp-server\n```\n\n### Add to Claude Code\n\n```bash\nclaude mcp add circle-so -- npx @alludium/circle-so-mcp-server\n```\n\nThen set your API key in the MCP server config at `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"circle-so\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"@alludium/circle-so-mcp-server\"],\n      \"env\": {\n        \"CIRCLE_SO_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### Add to Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"circle-so\": {\n      \"command\": \"npx\",\n      \"args\": [\"@alludium/circle-so-mcp-server\"],\n      \"env\": {\n        \"CIRCLE_SO_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/alludium/circle-so-mcp-server.git\ncd circle-so-mcp-server\nnpm install\nnpm run build\nCIRCLE_SO_API_KEY=your_api_key npm start\n```\n\n---\n\n## Getting Your API Key\n\n1. Log in to your Circle.so admin dashboard\n2. Go to **Settings** → **API**\n3. Generate an Admin API V1 token\n4. Set it as `CIRCLE_SO_API_KEY` in your environment or MCP config\n\n> **Note:** This server uses the Circle.so Admin API **V1**. V2 tokens are not compatible.\n\n---\n\n## Tools (71)\n\n### Community (2)\n\n| Tool | Description |\n|------|-------------|\n| `circle_get_community` | Get community details, settings, and configuration |\n| `circle_update_community` | Update community name and privacy settings |\n\n### Spaces (5)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_spaces` | List all spaces with sorting and pagination |\n| `circle_get_space` | Get space details by ID |\n| `circle_create_space` | Create a new space in a space group |\n| `circle_update_space` | Update space settings (name, visibility, display) |\n| `circle_delete_space` | Delete a space |\n\n### Space Groups (5)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_space_groups` | List all space groups |\n| `circle_get_space_group` | Get space group details |\n| `circle_create_space_group` | Create a new space group |\n| `circle_update_space_group` | Update space group settings |\n| `circle_delete_space_group` | Delete a space group |\n\n### Members (7)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_members` | List members with filters and pagination |\n| `circle_get_member` | Get member profile by ID |\n| `circle_search_member` | Search members by email |\n| `circle_create_member` | Invite or add a new member |\n| `circle_update_member` | Update member profile and role |\n| `circle_deactivate_member` | Deactivate a member account |\n| `circle_list_member_spaces` | List spaces a member belongs to |\n\n### Posts (5)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_posts` | List posts with filters by space, status, search |\n| `circle_get_post` | Get post details by ID |\n| `circle_create_post` | Create a post with HTML body content |\n| `circle_update_post` | Update post title, status, and metadata |\n| `circle_delete_post` | Delete a post |\n\n### Comments (4)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_comments` | List comments on a post |\n| `circle_get_comment` | Get comment details |\n| `circle_create_comment` | Add a comment to a post |\n| `circle_delete_comment` | Delete a comment |\n\n### Events (8)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_events` | List events with filters |\n| `circle_get_event` | Get event details |\n| `circle_create_event` | Create a new event |\n| `circle_update_event` | Update event details |\n| `circle_delete_event` | Delete an event |\n| `circle_list_event_attendees` | List event attendees |\n| `circle_add_event_attendee` | Add an attendee to an event |\n| `circle_remove_event_attendee` | Remove an attendee |\n\n### Courses (10)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_course_sections` | List sections in a course space |\n| `circle_get_course_section` | Get section details |\n| `circle_create_course_section` | Create a course section |\n| `circle_update_course_section` | Update a course section |\n| `circle_delete_course_section` | Delete a course section |\n| `circle_list_course_lessons` | List lessons in a section |\n| `circle_get_course_lesson` | Get lesson details |\n| `circle_create_course_lesson` | Create a lesson |\n| `circle_update_course_lesson` | Update a lesson |\n| `circle_delete_course_lesson` | Delete a lesson |\n\n### Member Tags (7)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_member_tags` | List all member tags |\n| `circle_get_member_tag` | Get tag details |\n| `circle_create_member_tag` | Create a new tag |\n| `circle_update_member_tag` | Update a tag |\n| `circle_delete_member_tag` | Delete a tag |\n| `circle_tag_member` | Apply a tag to a member |\n| `circle_untag_member` | Remove a tag from a member |\n\n### Space Members (4)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_space_members` | List members of a space |\n| `circle_get_space_member` | Get space membership details |\n| `circle_add_space_member` | Add a member to a space |\n| `circle_remove_space_member` | Remove a member from a space |\n\n### Topics (5)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_topics` | List topics in a space |\n| `circle_get_topic` | Get topic details |\n| `circle_create_topic` | Create a new topic |\n| `circle_update_topic` | Update a topic |\n| `circle_delete_topic` | Delete a topic |\n\n### Access Groups (8)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_access_groups` | List all access groups |\n| `circle_get_access_group` | Get access group details |\n| `circle_create_access_group` | Create an access group |\n| `circle_update_access_group` | Update an access group |\n| `circle_archive_access_group` | Archive an access group |\n| `circle_unarchive_access_group` | Unarchive an access group |\n| `circle_list_access_group_members` | List members in an access group |\n| `circle_add_access_group_member` | Add a member to an access group |\n\n### Moderation (1)\n\n| Tool | Description |\n|------|-------------|\n| `circle_list_flagged_content` | List content flagged for moderation |\n\n---\n\n## Prompts (10)\n\nBuilt-in prompt templates for common community management workflows. Use these from any MCP client that supports prompts.\n\n| Prompt | Description | Arguments |\n|--------|-------------|-----------|\n| `community_health_check` | Assess community health — spaces, members, activity, flagged content | — |\n| `welcome_new_member` | Draft a personalised welcome for a new member | `member_email` |\n| `draft_announcement` | Create a structured announcement post | `topic`, `space_name`? |\n| `plan_content_calendar` | Generate a multi-week content plan across spaces | `weeks`?, `focus`? |\n| `onboard_community` | Set up a new community from scratch with guided structure | `community_type`, `name` |\n| `moderate_flagged_content` | Review and action flagged content as a moderation queue | — |\n| `plan_event` | Plan and create a community event | `event_idea`, `date`? |\n| `create_space` | Design a new space with topics and welcome post | `purpose` |\n| `design_course` | Build a course with sections and lessons | `course_topic`, `lesson_count`? |\n| `manage_access_groups` | Review and manage member access tiers | `goal`? |\n\n---\n\n## API Notes\n\nThis server targets the **Circle.so Admin API V1** (`https://app.circle.so/api/v1`).\n\nKey things to know:\n\n- **Authentication**: Uses `Token` header auth (not Bearer). The server handles this automatically.\n- **Community ID**: Auto-discovered on startup from your API token. Injected into every request.\n- **Post bodies**: Use HTML strings in the `body` parameter. Circle wraps content in a `<div>` automatically.\n- **Post body on update**: The V1 API does not support updating post body content via PUT. To change post content, delete and recreate.\n- **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.\n- **Rate limits**: The server uses a 30-second timeout per request. Circle.so may impose its own rate limits.\n\n---\n\n## Project Structure\n\n```\nsrc/\n├── index.ts              # Entry point, server setup\n├── constants.ts          # API base URL, limits\n├── prompts.ts            # 10 MCP prompt templates\n├── schemas/\n│   └── common.ts         # Shared Zod schemas (pagination)\n├── services/\n│   └── api-client.ts     # HTTP client, auth, community ID\n└── tools/\n    ├── access-groups.ts  # Access group management (8 tools)\n    ├── comments.ts       # Comment CRUD (4 tools)\n    ├── community.ts      # Community get/update (2 tools)\n    ├── courses.ts        # Course sections & lessons (10 tools)\n    ├── events.ts         # Event CRUD + attendees (8 tools)\n    ├── member-tags.ts    # Tag CRUD + tagging (7 tools)\n    ├── members.ts        # Member management (7 tools)\n    ├── misc.ts           # Flagged content (1 tool)\n    ├── posts.ts          # Post CRUD (5 tools)\n    ├── space-groups.ts   # Space group CRUD (5 tools)\n    ├── space-members.ts  # Space membership (4 tools)\n    ├── spaces.ts         # Space CRUD (5 tools)\n    └── topics.ts         # Topic CRUD (5 tools)\n```\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run in development mode (auto-reload)\nnpm run dev\n\n# Clean build output\nnpm run clean\n```\n\n---\n\n## License\n\nMIT\n\n---\n\nBuilt with the [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).\n","readmeFilename":"README.md","_rev":"1-a779f8f4b44a4eada11a9a42519ec0a4"}