Chaturbate MCP Server

A Model Context Protocol (MCP) server that provides tools for querying Chaturbate's "Users Online v2" affiliates API. Built with TypeScript and designed for easy distribution to other developers.

Features

• 🔌 Stdio Transport - Works with any MCP client (Roo Code, Claude Desktop, etc.)
• 📦 npm Package - Easy installation via npx or local install
• 🎯 Three Tools - High-level model cards, advanced search, and low-level room filtering
• 🌐 Whitelabel Support - Works with custom Chaturbate domains
• 🚀 Zero Configuration - Works out of the box with sensible defaults

Quick Start

For MCP Client Users (Roo Code, Claude Desktop, etc.)

Add to your MCP configuration file:

Roo Code (.roo/mcp.json):

{
  "mcpServers": {
    "chaturbate": {
      "command": "npx",
      "args": ["-y", "chaturbate-mcp@latest"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "chaturbate": {
      "command": "npx",
      "args": ["-y", "chaturbate-mcp@latest"]
    }
  }
}

For Local Development

# Clone the repository
git clone <your-repo-url>
cd chaturbate-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Test the stdio server
npm test

Then configure your MCP client to use the local build:

{
  "mcpServers": {
    "chaturbate": {
      "command": "npx",
      "args": ["tsx", "src/server-stdio.ts"]
    }
  }
}

Available Tools

1) fetch_online_rooms

Low-level API access with full control over Chaturbate filters.

Input Parameters (all optional):

• client_ip (string) — IPv4/IPv6 or "request_ip"
• limit (number) — 1–500, default 100
• offset (number) — >=0, default 0
• exhibitionist (boolean)
• gender (array) — ["f"], ["m"], ["t"], ["c"]
• region (array) — ["asia"], ["europe_russia"], ["northamerica"], ["southamerica"], ["other"]
• tags (array) — Up to 5 tags, e.g., ["blonde", "young"]
• hd (boolean) — HD streams only
• api_origin (string) — Override API base URL for whitelabel domains

Output:

{
  "count": 150,
  "rooms": [
    {
      "username": "example_user",
      "room_subject": "Welcome to my room!",
      "image_url_360x270": "https://...",
      "tags": ["blonde", "new"],
      "num_users": 250,
      "num_followers": 5000,
      "age": 22,
      "gender": "f",
      "chat_room_url": "https://chaturbate.com/..."
    }
  ]
}

Example Usage:

{
  "tool": "fetch_online_rooms",
  "arguments": {
    "tags": ["blonde"],
    "gender": ["f"],
    "limit": 10,
    "hd": true
  }
}

2) search_performers

Advanced search tool that allows filtering performers by username, display name, and various criteria.

Input Parameters (all optional):

• query (string) — Search term to match against username or display name
• tags (array) — Up to 5 tags, e.g., ["blonde", "young"]
• gender (array) — ["f"], ["m"], ["t"], ["c"]
• region (array) — ["asia"], ["europe_russia"], ["northamerica"], ["southamerica"], ["other"]
• minUsers (number) — Minimum number of users in room
• maxUsers (number) — Maximum number of users in room
• minFollowers (number) — Minimum number of followers
• hd (boolean) — HD streams only
• exhibitionist (boolean)
• limit (number) — 1–500, default 50
• clientIp (string) — IPv4/IPv6 or "request_ip"
• api_origin (string) — Override API base URL for whitelabel domains

Output:

{
  "count": 25,
  "results": [
    {
      "username": "example_user",
      "display_name": "Example User ❤️",
      "room_subject": "Welcome to my room!",
      "image_url_360x270": "https://...",
      "image_url": "https://...",
      "tags": ["blonde", "new"],
      "num_users": 250,
      "num_followers": 5000,
      "age": 22,
      "gender": "f",
      "chat_room_url": "https://chaturbate.com/...",
      "country": "US"
    }
  ]
}

Example Usage:

{
  "tool": "search_performers",
  "arguments": {
    "query": "alice",
    "tags": ["blonde"],
    "gender": ["f"],
    "minUsers": 100,
    "limit": 10
  }
}

3) display_model_cards

High-level tool that returns sorted, formatted model cards ready for display.

Input Parameters:

• tags (array) — Up to 5 tags, e.g., ["blonde"]
• gender (string) — "f", "m", "t", or "c"
• limit (number) — Default 5, max 500
• client_ip (string) — Optional IP override
• sortBy (string) — "num_users" (default), "num_followers", or "seconds_online"
• api_origin (string) — Whitelabel domain override

Output:

{
  "cards": [
    {
      "title": "Display Name",
      "username": "example_user",
      "age": 22,
      "gender": "f",
      "image": "https://...",
      "subject": "Room subject line",
      "tags": ["blonde", "new"],
      "usersOnline": 250,
      "followers": 5000,
      "chatUrl": "https://chaturbate.com/...",
      "country": "US"
    }
  ]
}

The tool also returns a human-readable text summary ideal for LLMs.

Example Usage:

{
  "tool": "display_model_cards",
  "arguments": {
    "tags": ["blonde"],
    "gender": "f",
    "limit": 5,
    "sortBy": "num_users"
  }
}

Environment Variables

Optional configuration:

• CB_WM_SLUG — Your Chaturbate affiliate campaign slug (defaults to j1IHB)
• CB_API_ORIGIN — Custom API origin for whitelabel domains (defaults to https://chaturbate.com)

Example:

# Linux/macOS
export CB_WM_SLUG=your_slug
export CB_API_ORIGIN=https://www.whitelabel.com

# Windows PowerShell
$env:CB_WM_SLUG="your_slug"
$env:CB_API_ORIGIN="https://www.whitelabel.com"

# Windows Command Prompt
set CB_WM_SLUG=your_slug
set CB_API_ORIGIN=https://www.whitelabel.com

API Notes

Whitelabel Domains

When using api_origin parameter or CB_API_ORIGIN environment variable:

• Default: https://chaturbate.com/api/public/affiliates/onlinerooms/
• Whitelabel: https://www.whitelabel.com/api/public/affiliates/onlinerooms/

The origin changes the hostname, not a query parameter.

Required Parameters

The Chaturbate API requires:

• wm — Campaign slug (handled automatically via CB_WM_SLUG or default)
• client_ip — User's IP or "request_ip" (defaults to "request_ip")

Filter Options

• Gender: f (female), m (male), t (trans), c (couple)
• Region: asia, europe_russia, northamerica, southamerica, other
• Tags: Up to 5 tags per request
• HD: Boolean filter for HD streams only

Common Use Cases

Find Top Blonde Models

{
  "tool": "display_model_cards",
  "arguments": {
    "tags": ["blonde"],
    "gender": "f",
    "limit": 5,
    "sortBy": "num_users"
  }
}

Search for Specific Performers

{
  "tool": "search_performers",
  "arguments": {
    "query": "alice",
    "tags": ["blonde"],
    "minUsers": 50,
    "limit": 10
  }
}

Find Popular Rooms with Minimum Viewers

{
  "tool": "search_performers",
  "arguments": {
    "minUsers": 500,
    "gender": ["f"],
    "hd": true,
    "limit": 20
  }
}

Search HD Rooms by Multiple Tags

{
  "tool": "fetch_online_rooms",
  "arguments": {
    "tags": ["tattoo", "piercing"],
    "hd": true,
    "limit": 20
  }
}

Filter by Region and Gender

{
  "tool": "fetch_online_rooms",
  "arguments": {
    "gender": ["f"],
    "region": ["northamerica", "europe_russia"],
    "limit": 50
  }
}

Use Whitelabel Domain

{
  "tool": "display_model_cards",
  "arguments": {
    "tags": ["new"],
    "api_origin": "https://www.whitelabel.com",
    "limit": 10
  }
}

Development

HTTP Server (Optional)

An HTTP server with preview UI is included for development/testing:

# Start HTTP server
npm run dev:http

# Visit preview UI
open http://localhost:3000/preview/cards?tag=blonde&limit=5&gender=f

Note: The HTTP server is for development only. MCP clients use the stdio server.

Build & Test

# Build TypeScript to JavaScript
npm run build

# Test stdio server
npm test

# Run stdio server directly
npm run dev:stdio

Project Structure

chaturbate-mcp/
├── src/
│   ├── server-stdio.ts    # Stdio MCP server (main entry point)
│   ├── server.ts          # HTTP server (development/preview)
│   └── chaturbate.ts      # Chaturbate API client
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Distribution

Publishing to npm

1. Update version in package.json
2. Build the project: npm run build
3. Publish: npm publish

Users can then install with:

npx chaturbate-mcp@latest

Local Distribution

Share your repository, and users can install with:

{
  "mcpServers": {
    "chaturbate": {
      "command": "npx",
      "args": ["tsx", "/path/to/chaturbate-mcp/src/server-stdio.ts"]
    }
  }
}

Requirements

• Node.js >= 18
• Internet access to Chaturbate API

License

ISC

Support

For issues, questions, or contributions, please visit the repository.