Common Room MCP Server

⚠️ Note: This is an unofficial MCP server for Common Room

Here's a self-hosted MCP for integrating the Common Room API with Amazon Q CLI and Claude Code. The goal is to be able to ask questions and make updates easily for your own instance. Hope this makes it easier to keep your activities, segments, and organizations up to date! 🥳

How It Works

This MCP server exposes Common Room API functionality as tools that Q CLI can use:

1. MCP Protocol: Server communicates with Q CLI via Model Context Protocol
2. Tool Registration: Each Common Room API endpoint becomes a callable tool
3. Authentication: Uses your Common Room API key from environment variables
4. JSON Responses: All data returned as formatted JSON for easy reading

Common Room MCP Architecture

%%{init: {'flowchart': {'curve': 'basis'}}}%%
graph LR
    A["💻<br/>Q CLI"] -.-> B["🔌<br/>MCP Server"]
    C["💻<br/>Claude Code"] -.-> B
    B <--> D["☁️<br/>Common Room API"]
    
    style A fill:#6366f1,stroke:#000,stroke-width:3px,color:#fff
    style C fill:#ff9900,stroke:#000,stroke-width:3px,color:#000
    style B fill:#C11C84,stroke:#000,stroke-width:3px,color:#fff
    style D fill:#10b981,stroke:#000,stroke-width:3px,color:#000

When you ask Q CLI or Claude Code to "get Common Room activity types", it:

1. Calls the commonroom_get_activity_types tool
2. Server makes API request to Common Room
3. Returns formatted results to Q CLI
4. The agent presents the data to you in context

Quick Setup

1. Clone/download this repository
2. Install dependencies: pip install -r requirements.txt
3. Create API Signal: Go to https://app.commonroom.io/community/YOUR-COMMUNITY-ID/settings/sources/api to create an API signal and get your destinationSourceId (see Common Room docs)
4. Configure environment: Copy .env.example to .env and add your API key and destination ID
5. Configure MCP client (see INSTALL.md for detailed instructions)

Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "commonroom": {
      "command": "python",
      "args": ["/path/to/commonroom-mcp/server.py"],
      "env": {"COMMONROOM_KEY": "${COMMONROOM_KEY}"}
    }
  }
}

Amazon Q CLI

q chat --mcp-config ~/.config/amazon-q/mcp-config.json

📖 [Complete Installation Guide](INSTALL.md) 🔧 [Detailed Setup Guide](SETUP.md)

Setup

1. Install dependencies:

   cd /path/to/commonroom-mcp
   pip install -r requirements.txt

1. Get Common Room API Token:

• Go to your Common Room community settings: https://app.commonroom.io/community/YOUR-COMMUNITY-ID/settings/api-tokens
• Click "Create API Token"
• Give it a name (e.g., "MCP Server")
• Copy the generated token
• See Common Room API Token docs for details

1. Find your Destination ID (for adding activities/users):

• Go to Sources settings: https://app.commonroom.io/community/YOUR-COMMUNITY-ID/settings/sources
• Click on "API" source: https://app.commonroom.io/community/YOUR-COMMUNITY-ID/settings/sources/api
• If no API signal exists: Create one first (see Common Room API Signal docs)
• Copy the Destination ID number (e.g., 138683)

1. Configure environment:

   cp .env.example .env
   # Edit .env file with your credentials:
   # COMMONROOM_KEY=your_api_token_here
   # COMMONROOM_BASE_URL=https://app.commonroom.io/community/your-community-id
   # COMMONROOM_DESTINATION_ID=your_destination_id_here
   # COMMONROOM_SIGNAL_ID=your_signal_id_here (optional)

1. Test server:

   python server.py

Available Tools

• commonroom_get_activity_types - List all activity types
• commonroom_get_segments - List all segments
• commonroom_get_tags - List all tags
• commonroom_get_user - Get user by email (includes dashboard_url)
• commonroom_add_activity - Add activity
• commonroom_add_user - Add user
• commonroom_get_dashboard_urls - Get dashboard section URLs
• commonroom_get_member_url - Get individual member page URL
• commonroom_get_organization_url - Get individual organization page URL
• commonroom_get_segment_url - Get individual segment page URL

Usage in Q CLI

Once configured, you can use Common Room tools in Q CLI:

Get all Common Room activity types
Get segments for my team
Add a new blog post activity to Common Room
Show me the URL for user ID 12345

Example Queries

Get activity types:

Show me all Common Room activity types

Find user:

Get Common Room user data for [email protected]

Get member URL:

What's the URL for Common Room member 226882839?

Add activity:

Add a blog post activity to Common Room by [email protected] with title "Fire TV Development Guide"
Add webinar activity by Sarah Johnson ([email protected], Twitter: @sarahj, Company: TechCorp) with title "Building Smart TV Apps"

📋 [Click here for more examples prompts >> ](EXAMPLES.md)

Key Features

Auto-Generated IDs

• No manual ID management - Server automatically generates unique IDs for activities and users
• Format: activity_1703123456_a1b2c3d4 and user_1703123456_e5f6g7h8
• Deduplication - Common Room handles user merging based on email/social handles

Flexible User Data

Provide any combination of user information:

• Email address (recommended for deduplication)
• Social handles (Twitter, LinkedIn, GitHub, Discord, Slack)
• Company details (name, job title)
• Personal info (full name, location, bio)

Example: Just say "Add blog post by [email protected] (Twitter: @johndev)" and the server handles the rest!

Tool Details

• commonroom_get_activity_types - Returns all available activity types (article, webinar, etc.)
• commonroom_get_segments - Returns audience segments in your Common Room
• commonroom_get_tags - Returns all tags for categorization
• commonroom_get_user - Finds user by email address (includes dashboard_url)
• commonroom_add_activity - Creates new activity record
• commonroom_add_user - Creates new user record
• commonroom_get_dashboard_urls - Returns URLs for all dashboard sections (requires COMMONROOM_BASE_URL)
• commonroom_get_member_url - Returns URL for individual member page
• commonroom_get_organization_url - Returns URL for individual organization page
• commonroom_get_segment_url - Returns URL for individual segment page

Documentation

• [INSTALL.md](INSTALL.md) - Complete installation guide for Claude Code and Amazon Q CLI
• [SETUP.md](SETUP.md) - Detailed credential setup with screenshots and links
• [EXAMPLES.md](EXAMPLES.md) - Sample prompts and queries to test the MCP server
• [SPEC.md](SPEC.md) - Technical specification and requirements
• [openapi.json](openapi.json) - Common Room API specification

Keeping Up to Date

The server automatically checks for changes to Common Room's OpenAPI spec updates 30 seconds after startup and logs any available updates.

Manual update:

./update_spec.sh

Check for updates:

python version_checker.py

Security

• Never commit your .env file or API keys
• Use environment variables for sensitive data
• Keep your Common Room API token secure
• This server runs locally and doesn't send data to third parties

Support

Looking for support? Check out the Common Room docs or join the Uncommon community for product help.

For Common Room platform support, visit: https://www.commonroom.io/contact/

This MCP server is not officially supported by Common Room.

Contributing

See CONTRIBUTING.md for development guidelines.