Circle MCP Server

Circle MCP Server

  

Production-grade Model Context Protocol (MCP) server for the Circle community platform. This server enables AI assistants to interact with Circle.so communities through Google OAuth 2.0 authentication and provides 20+ tools for comprehensive community management.

---

📋 Table of Contents

• Features
• Architecture
• Prerequisites
• Installation
• Configuration
• Google Cloud Platform Setup
• Environment Variables
• Building & Testing
• IDE Integration
• Claude Desktop
• VS Code with Cline
• Other MCP Clients
• Available Tools
• Usage Examples
• Troubleshooting
• Development
• License

---

✨ Features

Core Capabilities

• 🔐 Google OAuth 2.0 Integration - Secure authentication via Google accounts
• 🔗 Circle API Integration - Seamless integration with Circle.so communities
• 🛡️ JWT Token Management - Automatic token refresh and secure storage
• 🚦 Rate Limiting - Built-in protection against API rate limits
• 🔄 Request Retry Logic - Exponential backoff for failed requests
• 📊 Comprehensive Logging - Winston-based structured logging
• 🎯 20+ Tools - Complete Circle API coverage
• 🔧 Type-Safe - Full TypeScript implementation with Zod validation

Security Features

• ✅ Secure credential storage
• ✅ Automatic token refresh
• ✅ OAuth 2.0 authorization code flow
• ✅ Read-only mode support
• ✅ Environment-based configuration

---

🏗️ Architecture

┌─────────────────┐
│   AI Assistant  │ (Claude Desktop, VS Code, etc.)
└────────┬────────┘
         │ MCP Protocol (stdio)
         ▼
┌─────────────────────────────────┐
│    Circle MCP Server            │
│  ┌──────────────────────────┐  │
│  │  Integrated Auth Manager │  │
│  │  ├─ GCP OAuth 2.0        │  │
│  │  └─ Circle JWT Auth      │  │
│  └──────────────────────────┘  │
│  ┌──────────────────────────┐  │
│  │  Circle API Client       │  │
│  │  ├─ Rate Limiting        │  │
│  │  ├─ Retry Logic          │  │
│  │  └─ Error Handling       │  │
│  └──────────────────────────┘  │
│  ┌──────────────────────────┐  │
│  │  20+ MCP Tools           │  │
│  └──────────────────────────┘  │
└─────────────┬───────────────────┘
              │ HTTPS
              ▼
    ┌──────────────────┐
    │  Circle.so API   │
    └──────────────────┘

Authentication Flow:

1. User triggers authenticate_with_google tool
2. OAuth server starts on localhost:3000
3. Browser opens for Google sign-in
4. User authorizes the application
5. Server receives OAuth callback with authorization code
6. Exchanges code for GCP access/refresh tokens
7. Retrieves user email from Google
8. Authenticates with Circle API using email
9. Stores both GCP and Circle tokens securely

---

📦 Prerequisites

Before you begin, ensure you have:

• Node.js v18 or higher (Download)
• npm v9 or higher (comes with Node.js)
• TypeScript knowledge (helpful but not required)
• Google Cloud Platform account (free tier works)
• Circle.so community with headless access token
• AI Assistant that supports MCP (Claude Desktop, VS Code with Cline, etc.)

---

🚀 Installation

1. Clone or Download the Project

cd /path/to/your/projects
# If you have this as a git repo:
git clone <repository-url> circle-mcp
cd circle-mcp

# Or if you already have the folder:
cd circle-mcp

2. Install Dependencies

npm install

This installs all required packages:

• @modelcontextprotocol/sdk - MCP protocol implementation
• google-auth-library - Google OAuth 2.0
• googleapis - Google APIs
• express - OAuth callback server
• axios - HTTP client
• winston - Logging
• zod - Schema validation
• And more...

---

⚙️ Configuration

1. Google Cloud Platform (GCP) Setup

Step 1.1: Create a GCP Project

1. Go to Google Cloud Console
2. Click "Select a project" → "New Project"
3. Enter project name (e.g., "Circle MCP Auth")
4. Click "Create"

Step 1.2: Enable Google+ API

1. In your project, go to APIs & Services → Library
2. Search for "Google+ API"
3. Click on it and press Enable

Step 1.3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Choose External (unless you have a Google Workspace)
3. Fill in the required fields:

• App name: Circle MCP Server
• User support email: Your email
• Developer contact: Your email

1. Click Save and Continue
2. Scopes: Skip this step (click Save and Continue)
3. Test users: Add your Google account email
4. Click Save and Continue

Step 1.4: Create OAuth 2.0 Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth 2.0 Client ID
3. Choose Web application
4. Configure:

• Name: Circle MCP OAuth Client
• Authorized redirect URIs: Add http://localhost:3000/auth/google/callback

1. Click Create
2. Save your credentials:

• Copy the Client ID (ends with .apps.googleusercontent.com)
• Copy the Client Secret (starts with GOCSPX-)

2. Environment Variables

Create a .env file in the project root:

# Create .env file
touch .env

Add the following configuration:

# Circle.so Configuration
CIRCLE_HEADLESS_TOKEN=your_circle_headless_token
CIRCLE_COMMUNITY_URL=https://your-community.circle.so
CIRCLE_HEADLESS_BASE_URL=https://app.circle.so

# Google Cloud Platform OAuth 2.0
GCP_CLIENT_ID=your-client-id-here.apps.googleusercontent.com
GCP_CLIENT_SECRET=GOCSPX-your-client-secret-here
GCP_REDIRECT_URI=http://localhost:3000/auth/google/callback
OAUTH_PORT=3000

# Server Configuration
READ_ONLY_MODE=false
LOG_LEVEL=info

How to Get Circle Credentials:

1. Circle Headless Token:

• Log in to your Circle community admin panel
• Go to Settings → API
• Generate a headless access token
• Copy the token

1. Circle Community URL:

• Your community's URL (e.g., https://learn.1to10x.ai)

Configuration Options:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | CIRCLE_HEADLESS_TOKEN | Yes | Circle API headless token | abc123... | | CIRCLE_COMMUNITY_URL | Yes | Your Circle community URL | https://community.circle.so | | GCP_CLIENT_ID | Yes | Google OAuth Client ID | 123-abc.apps.googleusercontent.com | | GCP_CLIENT_SECRET | Yes | Google OAuth Client Secret | GOCSPX-abcd1234 | | GCP_REDIRECT_URI | Yes | OAuth callback URL | http://localhost:3000/auth/google/callback | | OAUTH_PORT | No | OAuth server port (default: 3000) | 3000 | | READ_ONLY_MODE | No | Disable write operations (default: false) | false | | LOG_LEVEL | No | Logging level (default: info) | info |

---

🔨 Building & Testing

Build the Project

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

Verify Setup

node verify-setup.js

This checks:

• ✅ All required files exist
• ✅ Dependencies are installed
• ✅ Environment variables are configured
• ✅ TypeScript compiles without errors
• ✅ Port 3000 is available
• ✅ GCP credentials are valid

Test OAuth Flow

# Configuration test
node test-oauth-flow.js

# Automated server test
node test-oauth-automated.js

# Interactive OAuth testing
node test-oauth-interactive.js

Run the Server

npm start

---

🖥️ IDE Integration

1. Claude Desktop

Claude Desktop is Anthropic's official desktop app that supports MCP servers.

Step 1.1: Install Claude Desktop

Download from claude.ai

Step 1.2: Locate Configuration File

The configuration file location depends on your OS:

macOS: ``bash ~/Library/Application Support/Claude/claude_desktop_config.json ``

Windows: ``bash %APPDATA%\Claude\claude_desktop_config.json ``

Linux: ``bash ~/.config/Claude/claude_desktop_config.json ``

Step 1.3: Edit Configuration

Open claude_desktop_config.json and add:

{
  "mcpServers": {
    "circle": {
      "command": "node",
      "args": ["C:\\Users\\admin\\Desktop\\circle-mcp\\dist\\index.js"],
      "env": {
        "CIRCLE_HEADLESS_TOKEN": "your_circle_token_here",
        "CIRCLE_COMMUNITY_URL": "https://your-community.circle.so",
        "CIRCLE_HEADLESS_BASE_URL": "https://app.circle.so",
        "GCP_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GCP_CLIENT_SECRET": "GOCSPX-your-secret",
        "GCP_REDIRECT_URI": "http://localhost:3000/auth/google/callback",
        "OAUTH_PORT": "3000",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important Notes:

• Replace C:\\Users\\admin\\Desktop\\circle-mcp\\dist\\index.js with your actual path
• On Windows, use double backslashes (\\) or forward slashes (/)
• On macOS/Linux, use forward slashes (/)
• Replace all credential placeholders with your actual values

Step 1.4: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Relaunch Claude Desktop
3. The Circle MCP server will start automatically

Step 1.5: Verify Integration

In Claude Desktop, type:

Can you check if the Circle MCP server is connected?

If connected, Claude can use tools like: `` Please authenticate with Google so I can access Circle features. ``

2. VS Code with Cline

Cline is a VS Code extension that supports MCP servers.

Step 2.1: Install Cline Extension

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Cline"
4. Click Install

Step 2.2: Configure Cline

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Cline: Open Settings"
3. Navigate to MCP Servers section
4. Click "Edit in settings.json"

Add this configuration:

{
  "cline.mcpServers": {
    "circle": {
      "command": "node",
      "args": ["/absolute/path/to/circle-mcp/dist/index.js"],
      "env": {
        "CIRCLE_HEADLESS_TOKEN": "your_token",
        "CIRCLE_COMMUNITY_URL": "https://your-community.circle.so",
        "GCP_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GCP_CLIENT_SECRET": "GOCSPX-your-secret",
        "GCP_REDIRECT_URI": "http://localhost:3000/auth/google/callback"
      }
    }
  }
}

Step 2.3: Reload VS Code

1. Open Command Palette
2. Type "Developer: Reload Window"
3. Press Enter

Step 2.4: Use Circle Tools in Cline

Open Cline chat and try: `` Authenticate with Google to access Circle community ``

3. Other MCP Clients

MCP Inspector (Testing Tool)

For development and debugging:

npx @modelcontextprotocol/inspector node dist/index.js

Then open http://localhost:6274 in your browser.

Custom Integration

Any MCP-compatible client can connect using stdio transport:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/circle-mcp/dist/index.js'],
  env: { /* environment variables */ }
});

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

---

🛠️ Available Tools

The Circle MCP server provides 20+ tools across multiple categories:

Authentication Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | authenticate_with_google | Start Google OAuth flow | No | | check_auth_status | Check current authentication status | No | | logout | Logout and clear tokens | Yes |

Profile Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_my_profile | Get your Circle profile | Yes | | update_my_profile | Update your profile | Yes |

Course Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_my_courses | Get courses you're enrolled in | Yes | | get_course_details | Get detailed course information | Yes |

Post Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_posts | Get posts from community | Yes | | create_post | Create a new post | Yes | | update_post | Update an existing post | Yes | | delete_post | Delete a post | Yes | | like_post | Like a post | Yes | | unlike_post | Unlike a post | Yes |

Space Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_spaces | Get all community spaces | Yes | | get_space_members | Get members of a space | Yes |

Event Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_events | Get upcoming events | Yes | | get_event_details | Get event details | Yes | | rsvp_event | RSVP to an event | Yes |

Notification Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_notifications | Get your notifications | Yes | | mark_notification_read | Mark notification as read | Yes |

Message Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_direct_messages | Get your direct messages | Yes | | send_direct_message | Send a direct message | Yes |

Feed Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_feed | Get your personalized feed | Yes |

Comment Tools

| Tool | Description | Auth Required | |------|-------------|---------------| | get_post_comments | Get comments on a post | Yes | | create_comment | Create a comment | Yes | | update_comment | Update a comment | Yes | | delete_comment | Delete a comment | Yes |

---

📚 Usage Examples

Example 1: Authenticate with Google

User prompt in Claude Desktop: `` Please authenticate with Google so I can access Circle features ``

What happens:

1. MCP server receives authenticate_with_google tool call
2. OAuth server starts on http://localhost:3000
3. Browser opens for Google sign-in
4. User signs in and authorizes
5. Tokens are exchanged and stored
6. Circle authentication completes

Example 2: Get Your Profile

User prompt: `` Show me my Circle profile ``

MCP tool called: ``json { "name": "get_my_profile", "arguments": {} } ``

Response: ``json { "name": "John Doe", "email": "john@example.com", "bio": "Community member", "member_since": "2024-01-15" } ``

Example 3: Get Your Courses

User prompt: `` What courses am I enrolled in? ``

MCP tool called: ``json { "name": "get_my_courses", "arguments": {} } ``

Example 4: Create a Post

User prompt: `` Create a post in the General space with title "Hello World" and body "This is my first post!" ``

MCP tool called: ``json { "name": "create_post", "arguments": { "space_id": "12345", "title": "Hello World", "body": "This is my first post!" } } ``

Example 5: Get Events

User prompt: `` Show me upcoming events in the community ``

MCP tool called: ``json { "name": "get_events", "arguments": {} } ``

---

🐛 Troubleshooting

Issue: "GCP_CLIENT_ID not configured"

Solution:

1. Ensure .env file exists in project root
2. Add GCP_CLIENT_ID with your actual Google OAuth Client ID
3. Verify the Client ID ends with .apps.googleusercontent.com

Issue: "redirect_uri_mismatch"

Error Message: `` Error 400: redirect_uri_mismatch ``

Solution:

1. Go to Google Cloud Console
2. Navigate to APIs & Services → Credentials
3. Click on your OAuth 2.0 Client ID
4. Under "Authorized redirect URIs", add exactly:

   http://localhost:3000/auth/google/callback

1. Click Save
2. Wait 5 minutes for changes to propagate

Issue: "Port 3000 already in use"

Solution: Change the port in .env: ``env OAUTH_PORT=3001 GCP_REDIRECT_URI=http://localhost:3001/auth/google/callback ``

Remember: Update the redirect URI in Google Cloud Console too!

Issue: "User not found in Circle community"

Error Message: `` Circle authentication failed: User not found ``

Solution:

1. Ensure your Google account email is registered in the Circle community
2. Go to your Circle community and check your account email
3. Make sure it matches the Google account you're using to authenticate

Issue: Browser doesn't open during OAuth

Solution:

1. Check the terminal for the OAuth URL
2. Manually copy and paste the URL into your browser
3. Complete the authentication flow

Issue: TypeScript compilation errors

Solution: ```bash

Clean and rebuild

rm -rf dist node_modules npm install npm run build ```

Issue: "Cannot find module" errors

Solution: ```bash

Reinstall dependencies

npm install ```

Issue: MCP Server not showing in Claude Desktop

Solution:

1. Check claude_desktop_config.json syntax (valid JSON)
2. Verify the path to dist/index.js is absolute and correct
3. Ensure the server builds successfully (npm run build)
4. Restart Claude Desktop completely (quit and relaunch)
5. Check Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Issue: OAuth authentication fails silently

Solution:

1. Check if you added your email as a test user in GCP OAuth consent screen
2. Verify your GCP project has Google+ API enabled
3. Check server logs for detailed error messages
4. Try the interactive test: node test-oauth-interactive.js

---

👨‍💻 Development

Project Structure

circle-mcp/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── config/
│   │   └── config.ts            # Configuration management
│   ├── auth/
│   │   ├── gcp-auth.ts          # Google OAuth 2.0
│   │   ├── integrated-auth-manager.ts  # Auth orchestration
│   │   ├── oauth-server.ts      # OAuth callback server
│   │   ├── token-manager.ts     # Token refresh logic
│   │   └── user-storage.ts      # User data persistence
│   ├── api/
│   │   ├── client.ts            # Circle API client
│   │   └── endpoints.ts         # API endpoints
│   ├── tools/
│   │   ├── auth-wrapper.ts      # Authentication wrapper
│   │   ├── profile.ts           # Profile tools
│   │   ├── courses.ts           # Course tools
│   │   ├── posts.ts             # Post tools
│   │   ├── spaces.ts            # Space tools
│   │   ├── events.ts            # Event tools
│   │   ├── notifications.ts     # Notification tools
│   │   ├── messages.ts          # Message tools
│   │   ├── feed.ts              # Feed tools
│   │   └── comments.ts          # Comment tools
│   ├── types/
│   │   └── circle.ts            # TypeScript types
│   └── utils/
│       ├── error-handler.ts     # Error handling
│       ├── logger.ts            # Winston logger
│       └── validators.ts        # Input validation
├── dist/                        # Compiled JavaScript
├── test-oauth-flow.js           # Configuration test
├── test-oauth-automated.js      # Automated tests
├── test-oauth-interactive.js    # Interactive OAuth test
├── verify-setup.js              # Setup verification
├── package.json
├── tsconfig.json
├── .env                         # Environment variables (create this)
└── README.md

Available Scripts

# Development
npm run build          # Compile TypeScript
npm run typecheck      # Type check without building
npm start              # Start the MCP server
npm run dev            # Development mode with watch

# Testing
node verify-setup.js              # Verify complete setup
node test-oauth-flow.js           # Test OAuth configuration
node test-oauth-automated.js      # Automated server tests
node test-oauth-interactive.js    # Interactive OAuth testing

# Debugging
npx @modelcontextprotocol/inspector node dist/index.js  # MCP Inspector

Adding New Tools

1. Create a new file in src/tools/your-tool.ts
2. Import the authentication wrapper:

   import { withAuthentication } from './auth-wrapper.js';

1. Define your tool with authentication:

   export function registerYourTools(
     server: McpServer,
     apiClient: CircleAPIClient,
     authManager: IntegratedAuthManager
   ) {
     server.registerTool(
       'your_tool_name',
       {
         description: 'What your tool does',
         inputSchema: zodToJsonSchema(YourInputSchema)
       },
       withAuthentication(authManager, async (params) => {
         const email = (params as any).authenticatedEmail;
         // Your implementation
       })
     );
   }

1. Register in src/server.ts

Environment Variables for Development

# Enable debug logging
LOG_LEVEL=debug

# Test with read-only mode
READ_ONLY_MODE=true

# Use different OAuth port
OAUTH_PORT=3001

Running Tests

# Full test suite
npm run build
node verify-setup.js
node test-oauth-automated.js
node test-oauth-interactive.js

Debugging Tips

1. Enable debug logging:

   LOG_LEVEL=debug

1. Check MCP Inspector:

   npx @modelcontextprotocol/inspector node dist/index.js

1. Monitor server logs:

• Logs are output to stderr
• In Claude Desktop, check log files in the Claude logs directory

1. Test authentication separately:

   node test-oauth-interactive.js

---

📄 License

MIT License - see LICENSE file for details

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

---

📞 Support

If you encounter issues:

1. Check the Troubleshooting section
2. Review server logs for detailed error messages
3. Run node verify-setup.js to check configuration
4. Test OAuth flow with node test-oauth-interactive.js
5. Check GCP OAuth consent screen configuration
6. Verify your email is added as a test user (if app is in testing mode)

---

🎉 Quick Start Summary

# 1. Install dependencies
npm install

# 2. Create .env file with your credentials
cp .env.example .env  # Then edit with your values

# 3. Build the project
npm run build

# 4. Verify setup
node verify-setup.js

# 5. Test OAuth
node test-oauth-interactive.js

# 6. Add to Claude Desktop config
# Edit claude_desktop_config.json (see IDE Integration section)

# 7. Restart Claude Desktop and start chatting!

---

Built with ❤️ using Model Context Protocol