Integrate with Red Bee Media OTT Platform

Red Bee MCP Server

Model Context Protocol (MCP) Server for Red Bee Media OTT Platform

Connect to Red Bee Media streaming services from MCP-compatible clients like Claude Desktop, or integrate via HTTP/SSE for web applications. This server provides 33 tools for authentication, content search, user management, purchases, and system operations.

🆕 New: HTTP/SSE Mode

Version 1.4.0 now supports multiple operating modes:

• Stdio Mode (original): For local AI agents like Claude Desktop
• HTTP Mode: REST API with JSON-RPC for web integration
• SSE Mode: Server-Sent Events for real-time communication
• Both Modes: Run stdio and HTTP simultaneously

🚀 Quick Start

Option 1: Using uvx (Recommended)

# Test the server
uvx redbee-mcp --help

# Stdio mode (original)
uvx redbee-mcp --stdio --customer YOUR_CUSTOMER --business-unit YOUR_BU

# HTTP mode (new)
uvx redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU

# Both modes simultaneously
uvx redbee-mcp --both --customer YOUR_CUSTOMER --business-unit YOUR_BU

Option 2: Using pip

pip install redbee-mcp

# Same usage as uvx, but with redbee-mcp command
redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU

📋 Configuration

For Claude Desktop (Stdio Mode)

Add to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "redbee-mcp": {
      "command": "uvx",
      "args": ["redbee-mcp", "--stdio"],
      "env": {
        "REDBEE_CUSTOMER": "CUSTOMER_NAME",
        "REDBEE_BUSINESS_UNIT": "BUSINESS_UNIT_NAME"
      }
    }
  }
}

For Web Applications (HTTP Mode)

Start the HTTP server:

redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU

The server will be available at http://localhost:8000 with these endpoints:

Method	URL	Description
GET	/	API information
GET	/health	Server health check
POST	/	JSON-RPC MCP requests
GET	/sse	Server-Sent Events stream

🌐 HTTP/SSE API Usage

Example HTTP Requests

Health Check

curl http://localhost:8000/health

List Available Tools

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "1"
  }'

Search Content

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_content_v2",
      "arguments": {
        "query": "french films",
        "types": "MOVIE",
        "pageSize": 5
      }
    },
    "id": "search-1"
  }'

Web Integration Example

class RedBeeMCPClient {
  constructor(baseUrl = 'http://localhost:8000') {
    this.baseUrl = baseUrl;
  }

  async callTool(toolName, arguments) {
    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'tools/call',
        params: { name: toolName, arguments },
        id: Date.now().toString()
      })
    });
    return response.json();
  }

  async searchContent(query, options = {}) {
    return this.callTool('search_content_v2', {
      query,
      types: options.types || 'MOVIE,TV_SHOW',
      pageSize: options.pageSize || 10,
      ...options
    });
  }
}

// Usage
const mcp = new RedBeeMCPClient();
const results = await mcp.searchContent('comedy movies');

Server-Sent Events

Connect to real-time event stream:

const eventSource = new EventSource('http://localhost:8000/sse');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Event received:', data.type);
  
  if (data.type === 'welcome') {
    console.log('Connected with client ID:', data.client_id);
  } else if (data.type === 'tools') {
    console.log('Available tools:', data.tools.length);
  }
};

🔧 Environment Variables

Variable	Required	Description	Example
REDBEE_CUSTOMER	✅ Yes	Red Bee customer identifier	CUSTOMER_NAME
REDBEE_BUSINESS_UNIT	✅ Yes	Red Bee business unit	BUSINESS_UNIT_NAME
REDBEE_EXPOSURE_BASE_URL	❌ No	API base URL	https://exposure.api.redbee.live
REDBEE_USERNAME	❌ No	Username for authentication	user@example.com
REDBEE_PASSWORD	❌ No	Password for authentication	password123
REDBEE_SESSION_TOKEN	❌ No	Existing session token	eyJhbGciOiJIUzI1...
REDBEE_DEVICE_ID	❌ No	Device identifier	web-browser-123
REDBEE_CONFIG_ID	❌ No	Configuration ID	sandwich
REDBEE_TIMEOUT	❌ No	Request timeout in seconds	30

Available Tools

🔐 Authentication

• login_user - Authenticate with username/password
• create_anonymous_session - Create anonymous session
• validate_session_token - Validate existing session
• logout_user - Logout and invalidate session

📺 Content Management

• get_public_asset_details - Get asset details via public endpoint (no auth)
• search_content_v2 - Search V2: free text query in asset fields (including descriptions)
• get_asset_details - Get detailed asset information
• get_playback_info - Get streaming URLs and playback info
• search_assets_autocomplete - Autocomplete search suggestions
• get_epg_for_channel - Get Electronic Program Guide for a channel
• get_episodes_for_season - Get all episodes in a season
• get_assets_by_tag - Get assets by tag type (e.g., origin)
• list_assets - List assets with advanced filters
• search_multi_v3 - Multi-search for assets, tags, and participants
• get_asset_collection_entries - Get collection entries for an asset collection
• get_asset_thumbnail - Get thumbnail URL for an asset at a specific time
• get_seasons_for_series - Get all seasons for a TV series

👤 User Management

• signup_user - Create new user account
• change_user_password - Change user password
• get_user_profiles - Get user profiles
• add_user_profile - Add new user profile
• select_user_profile - Select active profile
• get_user_preferences - Get user preferences
• set_user_preferences - Set user preferences

💳 Purchases & Transactions

• get_account_purchases - Get user purchases
• get_account_transactions - Get transaction history
• get_offerings - Get available product offerings
• purchase_product_offering - Purchase a product
• cancel_purchase_subscription - Cancel subscription
• get_stored_payment_methods - Get saved payment methods
• add_payment_method - Add new payment method

⚙️ System Operations

• get_system_config - Get platform configuration
• get_system_time - Get server time
• get_user_location - Get user location by IP
• get_active_channels - Get active TV channels
• get_user_devices - Get registered devices
• delete_user_device - Delete a device

🧪 Testing

Test HTTP Server

# Start the server
redbee-mcp --http --customer DEMO --business-unit DEMO

# In another terminal, run the test script
python example_usage.py

Test Stdio Mode

# Using uvx
REDBEE_CUSTOMER=CUSTOMER_NAME REDBEE_BUSINESS_UNIT=BUSINESS_UNIT_NAME uvx redbee-mcp --stdio

# Using pip installation
REDBEE_CUSTOMER=CUSTOMER_NAME REDBEE_BUSINESS_UNIT=BUSINESS_UNIT_NAME redbee-mcp --stdio

Test MCP Protocol Manually

# Initialize and list tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"roots": {"listChanged": true}}, "clientInfo": {"name": "test", "version": "1.0.0"}}}
{"jsonrpc": "2.0", "method": "notifications/initialized"}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | uvx redbee-mcp --stdio

🏗️ Architecture

Multi-Mode Design

The server is architected with clean separation of concerns:

• McpHandler: Core business logic shared between all modes
• Stdio Server: Traditional MCP stdio interface for AI agents
• HTTP Server: FastAPI-based REST/SSE interface for web apps
• CLI: Multi-mode command line interface

File Structure

src/redbee_mcp/
├── handler.py          # Core business logic
├── server.py           # Stdio MCP server
├── http_server.py      # HTTP/SSE server
├── cli.py              # Multi-mode CLI
├── models.py           # Data models
└── tools/              # Tool modules
    ├── auth.py
    ├── content.py
    ├── purchases.py
    ├── system.py
    └── user_management.py

📖 Usage Examples

Search for French Movies (Stdio Mode)

Ask your AI assistant:

"Search for French documentaries about nature"

Search for Content (HTTP Mode)

const mcp = new RedBeeMCPClient();
const results = await mcp.searchContent('french documentaries', {
  types: 'MOVIE',
  locale: ['fr'],
  pageSize: 10
});

Get TV Show Information

# First search for a TV show
{
  "query": "Game of Thrones",
  "types": "TV_SHOW"
}

# Then get its seasons
{
  "assetId": "tv-show-asset-id"
}

User Authentication

{
  "username": "user@example.com",
  "password": "password123",
  "remember_me": true
}

🚀 Production Deployment

Docker

FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install -e .

EXPOSE 8000

# HTTP mode
CMD ["redbee-mcp", "--http", "--host", "0.0.0.0", "--port", "8000"]

Environment Setup

export REDBEE_CUSTOMER="your-customer"
export REDBEE_BUSINESS_UNIT="your-business-unit"
export REDBEE_EXPOSURE_BASE_URL="https://exposure.api.redbee.live"

Systemd Service

# /etc/systemd/system/redbee-mcp-http.service
[Unit]
Description=Red Bee MCP HTTP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/redbee-mcp
Environment=REDBEE_CUSTOMER=your-customer
Environment=REDBEE_BUSINESS_UNIT=your-business-unit
ExecStart=/usr/local/bin/redbee-mcp --http --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

🔒 Security Considerations

CORS Configuration

For production HTTP deployments, configure CORS properly in http_server.py:

self.app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],  # Specify allowed domains
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["Content-Type"],
)

📝 API Reference

The Red Bee MCP Server provides access to Red Bee Media Exposure API through:

• MCP Tools: For AI agents and local applications
• HTTP/JSON-RPC: For web applications and remote integration
• Server-Sent Events: For real-time updates

Each tool includes:

• Input validation with required and optional parameters
• Comprehensive error handling and messages
• Type safety for all inputs and outputs
• Detailed documentation and examples

🛠️ Development

Requirements

• Python 3.8+
• MCP SDK
• aiohttp for HTTP requests
• pydantic for data validation
• FastAPI and uvicorn for HTTP mode

Local Development

# Clone and install
git clone https://github.com/tamsibesson/redbee-mcp
cd redbee-mcp
pip install -e .

# Run in development mode
PYTHONPATH=src python -m redbee_mcp --http --customer TEST --business-unit TEST

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and questions:

• GitHub Issues: https://github.com/tamsibesson/redbee-mcp/issues
• Red Bee Media Documentation: https://www.redbeemedia.com/

🔗 Related

• Model Context Protocol
• Claude Desktop
• Red Bee Media
• FastAPI