๐Ÿš€ Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more โ†’

redbee-mcp

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

redbee-mcp

MCP Server for Red Bee Media OTT Platform - MCP Interface for Exposure APIs

1.4.2
Maintainers
1

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.

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

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

MethodURLDescription
GET/API information
GET/healthServer health check
POST/JSON-RPC MCP requests
GET/sseServer-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

VariableRequiredDescriptionExample
REDBEE_CUSTOMERโœ… YesRed Bee customer identifierCUSTOMER_NAME
REDBEE_BUSINESS_UNITโœ… YesRed Bee business unitBUSINESS_UNIT_NAME
REDBEE_EXPOSURE_BASE_URLโŒ NoAPI base URLhttps://exposure.api.redbee.live
REDBEE_USERNAMEโŒ NoUsername for authenticationuser@example.com
REDBEE_PASSWORDโŒ NoPassword for authenticationpassword123
REDBEE_SESSION_TOKENโŒ NoExisting session tokeneyJhbGciOiJIUzI1...
REDBEE_DEVICE_IDโŒ NoDevice identifierweb-browser-123
REDBEE_CONFIG_IDโŒ NoConfiguration IDsandwich
REDBEE_TIMEOUTโŒ NoRequest timeout in seconds30

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:

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts