Kaltura MCP Server

Instructions

Implementation Reference

• src/kaltura_mcp/tools/media.py:190-255 (handler)

  The core asynchronous handler function that implements the get_thumbnail_url tool logic. It validates inputs, fetches the media entry using Kaltura API, constructs a custom thumbnail URL with specified dimensions and optional video timestamp, and returns JSON with the result.
  async def get_thumbnail_url( manager: KalturaClientManager, entry_id: str, width: int = 120, height: int = 90, second: int = 5, ) -> str: """Get thumbnail URL for a media entry with custom dimensions.""" if not validate_entry_id(entry_id): return json.dumps({"error": "Invalid entry ID format"}, indent=2) # Validate numeric parameters if width <= 0 or width > 4096 or height <= 0 or height > 4096: return json.dumps( {"error": "Invalid dimensions: width and height must be between 1 and 4096"}, indent=2 ) if second < 0: return json.dumps({"error": "Invalid second parameter: must be non-negative"}, indent=2) try: client = manager.get_client() except Exception as e: return handle_kaltura_error(e, "get thumbnail URL", {"entry_id": entry_id}) # Get the entry to verify it exists entry = client.media.get(entry_id) # Build thumbnail URL with parameters base_url = entry.thumbnailUrl if not base_url: return json.dumps( { "error": "No thumbnail available for this entry", "entryId": entry_id, } ) # Add parameters for custom thumbnail params = [] if width: params.append(f"width={width}") if height: params.append(f"height={height}") if second and entry.mediaType == KalturaMediaType.VIDEO: params.append(f"vid_sec={second}") # Construct URL if params: separator = "&" if "?" in base_url else "?" thumbnail_url = base_url + separator + "&".join(params) else: thumbnail_url = base_url return json.dumps( { "entryId": entry_id, "entryName": entry.name, "mediaType": safe_serialize_kaltura_field(entry.mediaType), "thumbnailUrl": thumbnail_url, "width": width, "height": height, "second": second if entry.mediaType == KalturaMediaType.VIDEO else None, }, indent=2, )
• src/kaltura_mcp/server.py:319-344 (registration)

  MCP tool registration for get_thumbnail_url within the server's list_tools() method, defining the tool name, detailed description, and input schema for parameters entry_id (required), width, height, second.
  types.Tool( name="get_thumbnail_url", description="Get video THUMBNAIL/POSTER image. USE WHEN: Displaying video previews, creating galleries, showing video cards, generating custom thumbnails. RETURNS: Image URL with your specified size. EXAMPLES: 'Get thumbnail for video 1_abc123', 'Create 400x300 preview image', 'Get frame from 30 seconds in'. Can capture any frame from video.", inputSchema={ "type": "object", "properties": { "entry_id": { "type": "string", "description": "Video to get thumbnail from (format: '1_abc123')", }, "width": { "type": "integer", "description": "Thumbnail width in pixels (default: 120)", }, "height": { "type": "integer", "description": "Thumbnail height in pixels (default: 90)", }, "second": { "type": "integer", "description": "Video timestamp in seconds to capture (default: 5)", }, }, "required": ["entry_id"], }, ),
• src/kaltura_mcp/server.py:322-343 (schema)

  Input schema definition for the get_thumbnail_url tool, specifying JSON object with entry_id (string, required), optional integer parameters width (default 120), height (default 90), second (default 5).
  inputSchema={ "type": "object", "properties": { "entry_id": { "type": "string", "description": "Video to get thumbnail from (format: '1_abc123')", }, "width": { "type": "integer", "description": "Thumbnail width in pixels (default: 120)", }, "height": { "type": "integer", "description": "Thumbnail height in pixels (default: 90)", }, "second": { "type": "integer", "description": "Video timestamp in seconds to capture (default: 5)", }, }, "required": ["entry_id"], },
• src/kaltura_mcp/server.py:517-518 (registration)

  Dispatch/execution point in the server's call_tool() method that invokes the get_thumbnail_url handler with the Kaltura manager and parsed arguments.
  elif name == "get_thumbnail_url": result = await get_thumbnail_url(kaltura_manager, **arguments)