Red Bee MCP Server

Name: Red Bee MCP Server
Author: Tamsi

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.

PyPI version Python 3.8+

🆕 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:

🔧 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/