Circle社区MCP服务器

{
  "mcpServers": {
    "circle": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

git clone https://github.com/DeepakChander/circle-mcp.git
cd circle-mcp
npm install

cp .env.example .env

# Circle LMS (Required)
CIRCLE_HEADLESS_TOKEN=your_circle_headless_token
CIRCLE_ADMIN_V2_TOKEN=your_circle_admin_v2_token
CIRCLE_COMMUNITY_URL=https://your-community.circle.so
CIRCLE_HEADLESS_BASE_URL=https://app.circle.so

# Google OAuth (Required)
GCP_CLIENT_ID=your-client-id.apps.googleusercontent.com
GCP_CLIENT_SECRET=GOCSPX-your-secret
GCP_REDIRECT_URI=http://localhost:3000/callback

# Server
SERVER_URL=http://localhost:3000
PORT=3000

npm run build
npm run start:http

# Health check
curl http://localhost:3000/health

# OAuth metadata
curl http://localhost:3000/.well-known/oauth-authorization-server

{
  "mcpServers": {
    "circle": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

claude mcp add circle --transport http https://your-domain.com/mcp

{
  "mcp.servers": {
    "circle": {
      "type": "http",
      "url": "https://your-domain.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "circle": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "circle": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-domain.com/mcp"]
    }
  }
}

IDE (Cursor / Claude Code / VS Code / Windsurf / Claude Desktop)
    |
    |  POST /mcp  (Streamable HTTP + JSON-RPC)
    |  Authorization: Bearer <mcp_token>
    |
    v
+---------------------------------------------------+
|  Express HTTP Server                               |
|                                                    |
|  OAuth 2.1 Endpoints:                              |
|  GET  /.well-known/oauth-protected-resource        |
|  GET  /.well-known/oauth-authorization-server      |
|  POST /register  (Dynamic Client Registration)     |
|  GET  /authorize (redirects to Google OAuth)       |
|  GET  /callback  (Google -> Circle auth -> token)  |
|  POST /token     (code exchange + refresh)         |
|                                                    |
|  MCP Endpoints (Streamable HTTP):                  |
|  POST   /mcp  (JSON-RPC tool calls)               |
|  GET    /mcp  (SSE notifications)                  |
|  DELETE /mcp  (session termination)                |
+-------------------------+-------------------------+
                          |
            +-------------+-------------+
            |                           |
            v                           v
+------------------------+  +------------------------+
|  Circle Headless API   |  |  Circle Admin V2 API   |
|  (Per-User, 19 tools)  |  |  (Admin, 78 tools)     |
|  /api/v1/              |  |  /api/admin/v2/        |
+------------------------+  +------------------------+

1. IDE sends POST /mcp (no token)
2. Server returns 401 + WWW-Authenticate header
3. IDE discovers OAuth metadata via .well-known endpoints
4. IDE registers as OAuth client (POST /register)
5. IDE opens browser to /authorize with PKCE challenge
6. Server redirects to Google OAuth
7. User signs in with Google
8. Google redirects back to /callback with auth code
9. Server exchanges Google code for email
10. Server verifies email exists in Circle community
11. Server generates MCP authorization code
12. IDE exchanges code for MCP access token (POST /token)
13. IDE sends POST /mcp with Bearer token — 97 tools available!

sudo apt install nginx certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support
        proxy_buffering off;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 300s;
    }
}

npm run build
pm2 start dist/http-server.js --name circle-mcp
pm2 save

docker build -t circle-mcp .
docker run -d --env-file .env -p 3000:3000 --name circle-mcp circle-mcp

circle-mcp/
├── src/
│   ├── index.ts                      # Stdio entry point
│   ├── http-server.ts                # HTTP server entry point (production)
│   ├── server.ts                     # MCP server factory
│   ├── auth/
│   │   ├── mcp-oauth-server.ts       # OAuth 2.1 Authorization Server
│   │   ├── session-manager.ts        # Token-to-email + session tracking
│   │   ├── gcp-auth.ts               # Google OAuth 2.0 client
│   │   ├── auth.ts                   # Circle headless authentication
│   │   ├── integrated-auth-manager.ts
│   │   ├── token-manager.ts          # In-memory token storage
│   │   └── types.ts
│   ├── api/
│   │   ├── client.ts                 # Circle Headless API client
│   │   ├── admin-v2-client.ts        # Circle Admin V2 API client
│   │   └── endpoints.ts              # API URL builders
│   ├── tools/
│   │   ├── index.ts                  # Tool registration hub
│   │   ├── auth-wrapper.ts           # Auth wrappers
│   │   ├── profile.ts                # Member: Profile (2 tools)
│   │   ├── courses.ts                # Member: Courses (2 tools)
│   │   ├── posts.ts                  # Member: Posts (5 tools)
│   │   ├── spaces.ts                 # Member: Spaces (1 tool)
│   │   ├── events.ts                 # Member: Events (2 tools)
│   │   ├── notifications.ts          # Member: Notifications (1 tool)
│   │   ├── messages.ts               # Member: Messages (1 tool)
│   │   ├── feed.ts                   # Member: Feed (1 tool)
│   │   ├── comments.ts               # Member: Comments (4 tools)
│   │   ├── admin-members.ts          # Admin: Members (7 tools)
│   │   ├── admin-spaces.ts           # Admin: Spaces (13 tools)
│   │   ├── admin-content.ts          # Admin: Content (15 tools)
│   │   ├── admin-events.ts           # Admin: Events (8 tools)
│   │   ├── admin-courses.ts          # Admin: Courses (11 tools)
│   │   ├── admin-access.ts           # Admin: Access Groups (9 tools)
│   │   ├── admin-engagement.ts       # Admin: Engagement (9 tools)
│   │   └── admin-community.ts        # Admin: Community (6 tools)
│   ├── config/
│   │   ├── config.ts                 # Environment config loader
│   │   └── constants.ts              # API endpoint constants
│   ├── types/
│   │   ├── mcp.ts                    # MCP types
│   │   ├── circle.ts                 # Circle API types
│   │   └── index.ts
│   ├── prompts/
│   │   └── index.ts
│   ├── resources/
│   │   └── index.ts
│   └── utils/
│       ├── logger.ts                 # Winston logger
│       ├── errors.ts
│       ├── response-handler.ts
│       └── validators.ts
├── .env.example
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── nginx.conf
└── ecosystem.config.js               # PM2 config

npm run build        # Compile TypeScript
npm run start        # Start stdio server (local dev)
npm run start:http   # Start HTTP server (production)
npm run dev          # Dev mode with watch (stdio)
npm run dev:http     # Dev mode with watch (HTTP)
npm run typecheck    # Type check without emitting
npm run test         # Run tests