Kaltura MCP Server

Instructions

Implementation Reference

• src/kaltura_mcp/tools/analytics.py:102-195 (handler)

  Main handler function that implements the tool logic: validates inputs, sets default metrics based on report_type, calls the core get_analytics_graph function, reformats the response into a time-series 'series' structure optimized for charts and visualizations.

  async def get_analytics_timeseries(
      manager: KalturaClientManager,
      from_date: str,
      to_date: str,
      report_type: str = "content",
      metrics: Optional[List[str]] = None,
      entry_id: Optional[str] = None,
      interval: str = "days",
      dimension: Optional[str] = None,
  ) -> str:
      """
      Get time-series analytics data optimized for charts and visualizations.
  
      This function returns analytics data as time-series with consistent intervals,
      perfect for creating line charts, area charts, and trend visualizations.
  
      USE WHEN:
      - Creating charts or graphs showing trends over time
      - Building dashboards with visual analytics
      - Comparing metrics across different time periods
      - Showing growth or decline patterns
      - Visualizing seasonal trends
  
      Args:
          manager: Kaltura client manager
          from_date: Start date (YYYY-MM-DD)
          to_date: End date (YYYY-MM-DD)
          report_type: Type of report (default: "content")
          metrics: List of metrics to include (e.g., ["plays", "views", "avg_time"])
          entry_id: Optional specific entry ID
          interval: Time interval - "hours", "days", "weeks", "months" (default: "days")
          dimension: Optional dimension for grouping
  
      Returns:
          JSON with time-series data formatted for visualization:
          {
              "series": [
                  {
                      "metric": "count_plays",
                      "data": [{"date": "2024-01-01", "value": 150}, ...]
                  },
                  {
                      "metric": "unique_viewers",
                      "data": [{"date": "2024-01-01", "value": 89}, ...]
                  }
              ],
              "metadata": {...}
          }
  
      Examples:
          # Daily play counts for a video
          get_analytics_timeseries(manager, from_date, to_date,
                                  entry_id="1_abc", metrics=["plays"])
  
          # Monthly platform trends
          get_analytics_timeseries(manager, from_date, to_date,
                                  interval="months", report_type="platforms")
      """
      from .analytics_core import get_analytics_graph
  
      # If no metrics specified, use common ones based on report type
      if not metrics:
          metrics_map = {
              "content": ["count_plays", "unique_viewers", "avg_time_viewed"],
              "user_engagement": ["count_plays", "unique_known_users", "avg_completion_rate"],
              "geographic": ["count_plays", "unique_viewers"],
              "platforms": ["count_plays", "unique_viewers"],
          }
          metrics = metrics_map.get(report_type, ["count_plays", "unique_viewers"])
  
      result = await get_analytics_graph(
          manager=manager,
          from_date=from_date,
          to_date=to_date,
          report_type=report_type,
          entry_id=entry_id,
          interval=interval,
          dimension=dimension,
      )
  
      # Reformat to emphasize time-series nature
      data = json.loads(result)
      if "graphs" in data:
          # Rename "graphs" to "series" for clarity
          data["series"] = data.pop("graphs")
  
          # Add interval metadata
          data["metadata"] = {
              "interval": interval,
              "report_type": report_type,
              "date_range": data.get("dateRange", {}),
          }
  
      return json.dumps(data, indent=2)

• src/kaltura_mcp/server.py:147-181 (schema)

  MCP tool schema registration defining input parameters, types, descriptions, enums, and required fields for get_analytics_timeseries.

      name="get_analytics_timeseries",
      description="Get time-series analytics data optimized for charts and visualizations. Use this when creating graphs, dashboards, or tracking trends over time.",
      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')",
              },
              "report_type": {
                  "type": "string",
                  "description": "Report type (default: 'content')",
              },
              "metrics": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Metrics to include (e.g., ['plays', 'views'])",
              },
              "entry_id": {
                  "type": "string",
                  "description": "Optional: Track single video's performance over time (e.g., '1_abc123'). Leave empty for platform-wide trends.",
              },
              "interval": {
                  "type": "string",
                  "enum": ["hours", "days", "weeks", "months"],
                  "description": "Time grouping for data points (default: 'days'). Use 'hours' for <7 day ranges, 'days' for monthly, 'weeks' for quarterly, 'months' for yearly views. Affects data granularity.",
              },
          },
          "required": ["from_date", "to_date"],
      },
  ),

• src/kaltura_mcp/server.py:32-49 (registration)

  Import statement registering the get_analytics_timeseries handler function from tools module into the MCP server.

  from .tools import (
      get_analytics,
      get_analytics_timeseries,
      get_attachment_content,
      get_caption_content,
      get_download_url,
      get_geographic_breakdown,
      get_media_entry,
      get_quality_metrics,
      get_realtime_metrics,
      get_thumbnail_url,
      get_video_retention,
      list_analytics_capabilities,
      list_attachment_assets,
      list_caption_assets,
      list_categories,
      search_entries_intelligent,
  )

• src/kaltura_mcp/server.py:497-530 (registration)

  Dispatch logic in MCP server's call_tool method that routes calls to the get_analytics_timeseries handler when the tool name matches.

  if name == "get_media_entry":
      result = await get_media_entry(kaltura_manager, **arguments)
  elif name == "list_categories":
      result = await list_categories(kaltura_manager, **arguments)
  elif name == "get_analytics":
      result = await get_analytics(kaltura_manager, **arguments)
  elif name == "get_analytics_timeseries":
      result = await get_analytics_timeseries(kaltura_manager, **arguments)
  elif name == "get_video_retention":
      result = await get_video_retention(kaltura_manager, **arguments)
  elif name == "get_realtime_metrics":
      result = await get_realtime_metrics(kaltura_manager, **arguments)
  elif name == "get_quality_metrics":
      result = await get_quality_metrics(kaltura_manager, **arguments)
  elif name == "get_geographic_breakdown":
      result = await get_geographic_breakdown(kaltura_manager, **arguments)
  elif name == "list_analytics_capabilities":
      result = await list_analytics_capabilities(kaltura_manager, **arguments)
  elif name == "get_download_url":
      result = await get_download_url(kaltura_manager, **arguments)
  elif name == "get_thumbnail_url":
      result = await get_thumbnail_url(kaltura_manager, **arguments)
  elif name == "search_entries":
      result = await search_entries_intelligent(kaltura_manager, **arguments)
  elif name == "list_caption_assets":
      result = await list_caption_assets(kaltura_manager, **arguments)
  elif name == "get_caption_content":
      result = await get_caption_content(kaltura_manager, **arguments)
  elif name == "list_attachment_assets":
      result = await list_attachment_assets(kaltura_manager, **arguments)
  elif name == "get_attachment_content":
      result = await get_attachment_content(kaltura_manager, **arguments)
  else:
      return [types.TextContent(type="text", text=f"Unknown tool: {name}")]

• src/kaltura_mcp/tools/analytics.py:828-837 (helper)

  Helper metadata in list_analytics_capabilities describing the tool's purpose, use cases, and example usage for LLM discovery.

      "function": "get_analytics_timeseries",
      "purpose": "Time-series data for visualization",
      "use_cases": [
          "Creating charts and graphs",
          "Trend analysis over time",
          "Dashboard visualizations",
          "Growth tracking",
      ],
      "example": "get_analytics_timeseries(manager, from_date, to_date, interval='days')",
  },