Kaltura MCP Server

Instructions

Implementation Reference

• src/kaltura_mcp/tools/analytics.py:698-801 (handler)

  The primary handler function for the 'get_geographic_breakdown' tool. It fetches raw geographic analytics data from the core module, enhances it by calculating percentages, identifying top locations, and adding insights, then returns formatted JSON suitable for LLM consumption and visualization.
  async def get_geographic_breakdown( manager: KalturaClientManager, from_date: str, to_date: str, granularity: str = "country", region_filter: Optional[str] = None, metrics: Optional[List[str]] = None, ) -> str: """ Get analytics broken down by geographic location. This function provides location-based analytics at various levels of granularity, from global overview to city-level detail. USE WHEN: - Understanding global content reach - Planning regional content strategies - Analyzing market penetration - Optimizing CDN configuration - Compliance with regional requirements Args: manager: Kaltura client manager from_date: Start date (YYYY-MM-DD) to_date: End date (YYYY-MM-DD) granularity: Level of geographic detail: - "world": Global overview - "country": Country-level breakdown (default) - "region": State/province level - "city": City-level detail region_filter: Optional filter for specific region: - Country code (e.g., "US") for region/city views - Continent name for country views metrics: Optional list of metrics to include Returns: JSON with geographic distribution data: { "granularity": "country", "top_locations": [ { "location": "United States", "code": "US", "metrics": { "views": 45678, "unique_viewers": 12345, "avg_watch_time": 234.5, "percentage": 35.2 } }, ... ], "map_data": {...}, // GeoJSON format for visualization "insights": { "fastest_growing": ["India", "Brazil"], "highest_engagement": ["Canada", "UK"], "coverage": "127 countries" } } Examples: # Global country breakdown get_geographic_breakdown(manager, from_date, to_date) # US state-level analysis get_geographic_breakdown(manager, from_date, to_date, granularity="region", region_filter="US") # City-level for California get_geographic_breakdown(manager, from_date, to_date, granularity="city", region_filter="US-CA") """ from .analytics_core import get_geographic_analytics result = await get_geographic_analytics( manager=manager, from_date=from_date, to_date=to_date, level=granularity, country_filter=region_filter, ) # Enhance with insights data = json.loads(result) if "data" in data and len(data.get("data", [])) > 0: # Add percentage calculations total = sum(float(item.get("count_plays", 0)) for item in data["data"]) for item in data["data"]: plays = float(item.get("count_plays", 0)) item["percentage"] = round((plays / total * 100) if total > 0 else 0, 2) # Sort by plays and add top locations data["top_locations"] = sorted( data["data"], key=lambda x: float(x.get("count_plays", 0)), reverse=True )[:10] # Add insights data["insights"] = { "total_countries": len(data["data"]), "coverage": f"{len(data['data'])} locations", } return json.dumps(data, indent=2)
• src/kaltura_mcp/server.py:261-291 (registration)

  MCP tool registration in list_tools(), including the input schema definition, description, and use cases for the 'get_geographic_breakdown' tool.
  types.Tool( name="get_geographic_breakdown", description="Analyze viewer LOCATIONS and regional performance. USE WHEN: Understanding global reach, planning regional strategies, checking market penetration, optimizing CDN, compliance checks. RETURNS: Views/viewers by country/region/city with percentages. EXAMPLES: 'Which countries watch our content?', 'Show US state breakdown', 'Find top 10 cities for viewership'. Includes map-ready data.", inputSchema={ "type": "object", "properties": { "from_date": { "type": "string", "description": "Start date in YYYY-MM-DD format (e.g., '2024-01-01')", }, "to_date": { "type": "string", "description": "End date in YYYY-MM-DD format (e.g., '2024-01-31')", }, "granularity": { "type": "string", "enum": ["world", "country", "region", "city"], "description": "Location detail level (default: 'country'): 'world' = continents, 'country' = nations, 'region' = states/provinces, 'city' = cities. Higher detail requires region_filter.", }, "region_filter": { "type": "string", "description": "Zoom into specific area: For region view use country code (e.g., 'US' for US states), for city view use 'US-CA' for California cities. Required for region/city granularity.", }, "metrics": { "type": "array", "items": {"type": "string"}, "description": "Metrics to include", }, }, "required": ["from_date", "to_date"], },
• src/kaltura_mcp/server.py:511-512 (registration)

  Dispatch registration in the call_tool handler that routes requests for 'get_geographic_breakdown' to the implementation function.
  elif name == "get_geographic_breakdown": result = await get_geographic_breakdown(kaltura_manager, **arguments)
• src/kaltura_mcp/tools/analytics_core.py:1116-1142 (helper)

  Supporting helper function that maps granularity levels to specific Kaltura report types (e.g., 'geographic_country'), applies country filters, and delegates to the enhanced analytics core implementation.
  async def get_geographic_analytics( manager: KalturaClientManager, from_date: str, to_date: str, level: str = "country", country_filter: Optional[str] = None, ) -> str: """Get geographic analytics at different levels.""" geo_map = { "world": "geographic", "country": "geographic_country", "region": "geographic_region", "city": "geographic_city", } filters = {} if country_filter and level in ["region", "city"]: filters["countryIn"] = country_filter return await get_analytics_enhanced( manager=manager, from_date=from_date, to_date=to_date, report_type=geo_map.get(level, "geographic_country"), filters=filters, )
• src/kaltura_mcp/tools/__init__.py:4-7 (registration)

  Import/export registration of the get_geographic_breakdown function in the tools module __init__ for easy access across the package.
  from .analytics import ( get_analytics, get_analytics_timeseries, get_geographic_breakdown,