# twelvelabs-mcp-server MCP server TwelveLabs MCP: video indexing, search, analysis, and embeddings for AI applications. ## Links - Registry page: https://www.getdrio.com/mcp/io-twelvelabs-twelvelabs-mcp-server - Website: https://twelvelabs.io ## Install - Endpoint: https://mcp.twelvelabs.io - Auth: Auth required by registry metadata ## Setup notes - Remote header: X-api-key (required; secret) - Remote header: X-api-key (required; secret) - The upstream registry signals required auth or secrets. - Remote endpoint: https://mcp.twelvelabs.io - Header: X-api-key - Remote endpoint: https://mcp.twelvelabs.io/mcp - Header: X-api-key ## Tools - create-index - Create a new twelvelabs video index. An index is a basic unit for organizing and storing video data consisting of video embeddings and metadata. Indexes facilitate information retrieval and processing. If you plan to use search or video embedding, you should use the embedding model. If you plan to analyse videos to generate summaries, chapters, highlights, etc., you should use the generative model. If you don't provide a model, we will use both models by default. Endpoint: https://mcp.twelvelabs.io - list-indexes - List all twelvelabs video indexes. Endpoint: https://mcp.twelvelabs.io - delete-index - Delete a twelvelabs video index Endpoint: https://mcp.twelvelabs.io - start-video-indexing-task - Start a twelvelabs video indexing task. This will allow the video to be used by the embedding model and searched in natural language. If no indexId is provided, we will add the video to the default index. You can provide either a videoUrl (for remote videos), a videoFilePath (for local video files), or a folderFilePath (to index all videos in a local folder). If both videoUrl and videoFilePath are provided, we will use the videoUrl. Supports Google Drive links (file or folder). For Google Drive folders, all MP4 videos will be indexed and multiple tasks will be started. You can also pass optional userMetadata as a JSON string of key-value pairs to attach metadata to the indexed video(s). Endpoint: https://mcp.twelvelabs.io - get-video-indexing-tasks - **Legacy.** Prefer get-indexed-asset for new code (it uses TL's current /indexes/{id}/indexed-assets endpoint and is forward-compatible). This tool calls TL's deprecated /tasks endpoint, which still works today but will be removed in a future TL API release. Kept here so existing callers that only have a taskId (no indexId) keep working. If you provide a taskId, returns details (including the status) of that task. If not, returns the details of the latest 10 indexing tasks created. Possible statuses: - Validating, Pending, Queued, Indexing, Ready, Failed. Endpoint: https://mcp.twelvelabs.io - get-indexed-asset - Retrieve an indexed asset by (indexId, indexedAssetId) — returns its status, system metadata, and optional embeddings/transcription. Prefer this tool over the legacy get-video-indexing-tasks. It uses TL's current /indexes/{indexId}/indexed-assets/{indexedAssetId} endpoint, which replaces the deprecated /tasks endpoint and is forward-compatible. Statuses: pending, queued, indexing, ready, failed. Endpoint: https://mcp.twelvelabs.io - list-videos - List all videos in a twelvelabs video index. If you don't provide an indexId, we will use the default index. This tool will return for each video of the index: - the videoId: needed for video analysis. - the original video filename (if there is one). Use this tool if you don't know the videoId of the video the user wants to analyse, you can display the different filenames and ask the user to select the video they want to analyse. Endpoint: https://mcp.twelvelabs.io - search - Search in twelvelabs videos using natural language descriptions. The twelvelabs platform interprets your query to find matching content based on visual elements, actions, sounds, and on-screen text. The search is performed on all videos in the index (or the default index if no index is provided). It will return the start and end time of the matching segments in the video. The search results include: - Filename and videoId for each matching video - user_metadata (if any was attached during indexing) - Thumbnail URLs for each segment (pre-signed S3 URLs, valid for 1 hour) - Start/end times and relevance rank for each segment For each video that has matching segments, you should display: - Filename of the video - user_metadata key-value pairs - A table of segments with rank, timecode, and a clickable hyperlink for the thumbnail (do NOT use markdown image syntax, use a text hyperlink like [View thumbnail](url) instead). Supports three search modes: - Text only: provide just a query string - Image only: provide queryMediaUrl or queryMediaFile with queryMediaType "image" - Composed (text + image): provide both query and an image (via URL or file path) for refined results (e.g. image of a car + "red color"). Requires Marengo 3.0. For entity search, include the entity ID in the query using the format: "<@entity_id> action description" Endpoint: https://mcp.twelvelabs.io - create-entity-collection - Create a new entity collection. Entity collections group related entities (people or objects) for entity search. For example, create a collection per sports team or film cast. Requires Marengo 3.0. Endpoint: https://mcp.twelvelabs.io - list-entity-collections - List all entity collections. Entity collections contain entities (people/objects) used for entity search. Endpoint: https://mcp.twelvelabs.io - delete-entity-collection - Delete an entity collection and all its entities. Endpoint: https://mcp.twelvelabs.io - create-asset - Upload an image or video file as a TwelveLabs asset. Assets are reference files used by other tools: - Image assets → reference images for entities (see create-entity). - Video assets → input to async-analyse-video via the assetId parameter (alternative to videoUrl/base64Video). Provide either a publicly accessible URL or an absolute path to a local file. The asset's media type is inferred from the file content. Endpoint: https://mcp.twelvelabs.io - delete-asset - Delete an asset (image or video) by ID. By default, the request is rejected if any indexed video references the asset; pass force=true to delete anyway (the platform will unlink any entity associations). This action cannot be undone. Endpoint: https://mcp.twelvelabs.io - create-entity - Create an entity within a collection. An entity represents a specific person or object you want to find in videos. You must provide at least one image asset ID (created via create-asset with an image URL/file). Video assets are rejected — they are inputs for async-analyse-video, not entity reference material. Multiple reference images improve accuracy. After creating an entity, search for it using: <@entity_id> action description Endpoint: https://mcp.twelvelabs.io - list-entities - List all entities in an entity collection. Endpoint: https://mcp.twelvelabs.io - delete-entity - Delete an entity from a collection. Endpoint: https://mcp.twelvelabs.io - start-video-embeddings-task - Start a new twelvelabs video embeddings task that uploads a video to the platform and creates one or multiple video embeddings. Endpoint: https://mcp.twelvelabs.io - get-video-embeddings-tasks - Get details about video embeddings tasks. If you provide a taskId, we will return details (including the status) of that task. If not we will return the details of the latest 10 embeddings tasks that were created. Possible statuses are processing, ready, or failed. Endpoint: https://mcp.twelvelabs.io - retrieve-video-embeddings - Retrieves the video embeddings from a ready twelvelabs video embeddings task or from an indexed video. Endpoint: https://mcp.twelvelabs.io - sync-analyse-video - Synchronously analyse a video and return the generated text (or structured JSON) inline. **Input sources** (provide exactly one): - `videoId` — pre-indexed video. **Pegasus 1.2 only** (legacy, kept for backwards compatibility). - `videoUrl` / `assetId` / `base64Video` — direct sources (1.2.4+). Work with both Pegasus 1.2 and 1.5. **Model selection** (`modelName`): - `pegasus1.2` (default, server-side) — general analysis; accepts videoId. - `pegasus1.5` — adds clip windowing (`startTime`/`endTime`), structured prompts (`promptV2` with image refs), and larger token budget. Does NOT accept videoId. **Prompting**: Either `prompt` (plain text, max 2000 tokens) or `promptV2` (structured prompt with `<@name>` image references, Pegasus 1.5 only). Mutually exclusive. **Structured JSON output**: Set `jsonSchema` to constrain output to a JSON Schema (Draft 2020-12). Sync supports json_schema response_format only. Good for quick open-ended Q&A, summaries, chapters, highlights, or any prompt-guided text output. For videos over 1 hour or for time-based metadata segmentation, use `async-analyse-video`. Endpoint: https://mcp.twelvelabs.io - async-analyse-video - Asynchronously analyse a video with Pegasus 1.5 (default). Takes a videoUrl, assetId, or base64Video directly — NO prior indexing required. Handles videos up to 2 hours; longer videos are rejected by the Twelve Labs API with a 400. Pegasus 1.5 supports both prompt-only general analysis and time_based_metadata segmentation; pick the mode by setting analysisMode and segmentDefinitions (segmentation) or just prompt (general). Pegasus 1.2 is retained for backwards compatibility — set modelName="pegasus1.2" only if you need to preserve an existing 1.2 workflow (1.2 is on a deprecation path). This is the right tool when: - You have a URL or local upload, not an indexed videoId. - The video is over 1 hour long (sync analyse is capped at 1h). - You want time-based metadata segmentation (set analysisMode="time_based_metadata" + segmentDefinitions; Pegasus 1.5 only). - You want multimodal prompting: attach up to 4 reference images per segment definition via segmentDefinitions[].mediaSources. For plain prompt Q&A on an already-indexed video, sync-analyse-video is faster (Pegasus 1.2, returns inline). Use that when you already have a videoId. This tool is fire-and-forget: it returns a taskId and status immediately. Poll status with get-analyse-task (every 5-10s; a 2-hour video may take several minutes). When status is "ready", the result lives in the task response. Input rules: - Provide exactly one of videoUrl, assetId, or base64Video. - If using assetId, ensure the asset status is "ready" first (assets still processing will be rejected). - videoUrl must be a direct http(s) link to raw media — YouTube/Drive/Dropbox share links are not accepted. - base64Video max 30 MB encoded; prefer URL or asset for larger inputs. - prompt drives general (prompt-based) analysis on either model. It cannot be combined with analysisMode="time_based_metadata". - analysisMode="time_based_metadata" requires modelName="pegasus1.5" (the default) and segmentDefinitions. - segmentDefinitions requires analysisMode="time_based_metadata" and selects structured per-segment output. - jsonSchema (optional) constrains general-mode output to structured JSON (JSON Schema Draft 2020-12 subset). Cannot be combined with segmentDefinitions. 1.2.4 additions (all optional): - promptV2: structured prompt with <@name> image references (Pegasus 1.5 only). Mutually exclusive with prompt. - startTime / endTime: clip the analysis window to a sub-range (Pegasus 1.5 only). Mutually exclusive with segmentDefinition.timeRanges. - segmentDefinition.timeRanges: restrict TBM extraction to specific time windows. Mutually exclusive with top-level startTime/endTime and min/maxSegmentDuration. - customId: caller-supplied identifier (1-64 chars, [A-Za-z0-9_-]) returned in task responses. Endpoint: https://mcp.twelvelabs.io - get-analyse-task - Retrieve the status and results of an async analyse task created via async-analyse-video. Call this repeatedly (every 5-10 seconds) after async-analyse-video until status is "ready" or "failed". When status is "ready", the result.data field holds the generated text. In time_based_metadata mode, result.data is a JSON-encoded string keyed by each segmentDefinition id — parse it yourself. Endpoint: https://mcp.twelvelabs.io - list-analyse-tasks - List async analyse tasks in your account, newest first. Supports pagination and filtering by status, source videoUrl, source assetId, or analysisMode. Returns a compact summary per task — use get-analyse-task for the full result of a specific task. Endpoint: https://mcp.twelvelabs.io - delete-analyse-task - Delete an async analyse task by ID. Tasks that are still processing cannot be deleted — wait for them to finish or fail, or leave them alone (they expire server-side eventually). Endpoint: https://mcp.twelvelabs.io - create-index - Create a new twelvelabs video index. An index is a basic unit for organizing and storing video data consisting of video embeddings and metadata. Indexes facilitate information retrieval and processing. If you plan to use search or video embedding, you should use the embedding model. If you plan to analyse videos to generate summaries, chapters, highlights, etc., you should use the generative model. If you don't provide a model, we will use both models by default. Endpoint: https://mcp.twelvelabs.io/mcp - list-indexes - List all twelvelabs video indexes. Endpoint: https://mcp.twelvelabs.io/mcp - delete-index - Delete a twelvelabs video index Endpoint: https://mcp.twelvelabs.io/mcp - start-video-indexing-task - Start a twelvelabs video indexing task. This will allow the video to be used by the embedding model and searched in natural language. If no indexId is provided, we will add the video to the default index. You can provide either a videoUrl (for remote videos), a videoFilePath (for local video files), or a folderFilePath (to index all videos in a local folder). If both videoUrl and videoFilePath are provided, we will use the videoUrl. Supports Google Drive links (file or folder). For Google Drive folders, all MP4 videos will be indexed and multiple tasks will be started. You can also pass optional userMetadata as a JSON string of key-value pairs to attach metadata to the indexed video(s). Endpoint: https://mcp.twelvelabs.io/mcp - get-video-indexing-tasks - **Legacy.** Prefer get-indexed-asset for new code (it uses TL's current /indexes/{id}/indexed-assets endpoint and is forward-compatible). This tool calls TL's deprecated /tasks endpoint, which still works today but will be removed in a future TL API release. Kept here so existing callers that only have a taskId (no indexId) keep working. If you provide a taskId, returns details (including the status) of that task. If not, returns the details of the latest 10 indexing tasks created. Possible statuses: - Validating, Pending, Queued, Indexing, Ready, Failed. Endpoint: https://mcp.twelvelabs.io/mcp - get-indexed-asset - Retrieve an indexed asset by (indexId, indexedAssetId) — returns its status, system metadata, and optional embeddings/transcription. Prefer this tool over the legacy get-video-indexing-tasks. It uses TL's current /indexes/{indexId}/indexed-assets/{indexedAssetId} endpoint, which replaces the deprecated /tasks endpoint and is forward-compatible. Statuses: pending, queued, indexing, ready, failed. Endpoint: https://mcp.twelvelabs.io/mcp - list-videos - List all videos in a twelvelabs video index. If you don't provide an indexId, we will use the default index. This tool will return for each video of the index: - the videoId: needed for video analysis. - the original video filename (if there is one). Use this tool if you don't know the videoId of the video the user wants to analyse, you can display the different filenames and ask the user to select the video they want to analyse. Endpoint: https://mcp.twelvelabs.io/mcp - search - Search in twelvelabs videos using natural language descriptions. The twelvelabs platform interprets your query to find matching content based on visual elements, actions, sounds, and on-screen text. The search is performed on all videos in the index (or the default index if no index is provided). It will return the start and end time of the matching segments in the video. The search results include: - Filename and videoId for each matching video - user_metadata (if any was attached during indexing) - Thumbnail URLs for each segment (pre-signed S3 URLs, valid for 1 hour) - Start/end times and relevance rank for each segment For each video that has matching segments, you should display: - Filename of the video - user_metadata key-value pairs - A table of segments with rank, timecode, and a clickable hyperlink for the thumbnail (do NOT use markdown image syntax, use a text hyperlink like [View thumbnail](url) instead). Supports three search modes: - Text only: provide just a query string - Image only: provide queryMediaUrl or queryMediaFile with queryMediaType "image" - Composed (text + image): provide both query and an image (via URL or file path) for refined results (e.g. image of a car + "red color"). Requires Marengo 3.0. For entity search, include the entity ID in the query using the format: "<@entity_id> action description" Endpoint: https://mcp.twelvelabs.io/mcp - create-entity-collection - Create a new entity collection. Entity collections group related entities (people or objects) for entity search. For example, create a collection per sports team or film cast. Requires Marengo 3.0. Endpoint: https://mcp.twelvelabs.io/mcp - list-entity-collections - List all entity collections. Entity collections contain entities (people/objects) used for entity search. Endpoint: https://mcp.twelvelabs.io/mcp - delete-entity-collection - Delete an entity collection and all its entities. Endpoint: https://mcp.twelvelabs.io/mcp - create-asset - Upload an image or video file as a TwelveLabs asset. Assets are reference files used by other tools: - Image assets → reference images for entities (see create-entity). - Video assets → input to async-analyse-video via the assetId parameter (alternative to videoUrl/base64Video). Provide either a publicly accessible URL or an absolute path to a local file. The asset's media type is inferred from the file content. Endpoint: https://mcp.twelvelabs.io/mcp - delete-asset - Delete an asset (image or video) by ID. By default, the request is rejected if any indexed video references the asset; pass force=true to delete anyway (the platform will unlink any entity associations). This action cannot be undone. Endpoint: https://mcp.twelvelabs.io/mcp - create-entity - Create an entity within a collection. An entity represents a specific person or object you want to find in videos. You must provide at least one image asset ID (created via create-asset with an image URL/file). Video assets are rejected — they are inputs for async-analyse-video, not entity reference material. Multiple reference images improve accuracy. After creating an entity, search for it using: <@entity_id> action description Endpoint: https://mcp.twelvelabs.io/mcp - list-entities - List all entities in an entity collection. Endpoint: https://mcp.twelvelabs.io/mcp - delete-entity - Delete an entity from a collection. Endpoint: https://mcp.twelvelabs.io/mcp - start-video-embeddings-task - Start a new twelvelabs video embeddings task that uploads a video to the platform and creates one or multiple video embeddings. Endpoint: https://mcp.twelvelabs.io/mcp - get-video-embeddings-tasks - Get details about video embeddings tasks. If you provide a taskId, we will return details (including the status) of that task. If not we will return the details of the latest 10 embeddings tasks that were created. Possible statuses are processing, ready, or failed. Endpoint: https://mcp.twelvelabs.io/mcp - retrieve-video-embeddings - Retrieves the video embeddings from a ready twelvelabs video embeddings task or from an indexed video. Endpoint: https://mcp.twelvelabs.io/mcp - sync-analyse-video - Synchronously analyse a video and return the generated text (or structured JSON) inline. **Input sources** (provide exactly one): - `videoId` — pre-indexed video. **Pegasus 1.2 only** (legacy, kept for backwards compatibility). - `videoUrl` / `assetId` / `base64Video` — direct sources (1.2.4+). Work with both Pegasus 1.2 and 1.5. **Model selection** (`modelName`): - `pegasus1.2` (default, server-side) — general analysis; accepts videoId. - `pegasus1.5` — adds clip windowing (`startTime`/`endTime`), structured prompts (`promptV2` with image refs), and larger token budget. Does NOT accept videoId. **Prompting**: Either `prompt` (plain text, max 2000 tokens) or `promptV2` (structured prompt with `<@name>` image references, Pegasus 1.5 only). Mutually exclusive. **Structured JSON output**: Set `jsonSchema` to constrain output to a JSON Schema (Draft 2020-12). Sync supports json_schema response_format only. Good for quick open-ended Q&A, summaries, chapters, highlights, or any prompt-guided text output. For videos over 1 hour or for time-based metadata segmentation, use `async-analyse-video`. Endpoint: https://mcp.twelvelabs.io/mcp - async-analyse-video - Asynchronously analyse a video with Pegasus 1.5 (default). Takes a videoUrl, assetId, or base64Video directly — NO prior indexing required. Handles videos up to 2 hours; longer videos are rejected by the Twelve Labs API with a 400. Pegasus 1.5 supports both prompt-only general analysis and time_based_metadata segmentation; pick the mode by setting analysisMode and segmentDefinitions (segmentation) or just prompt (general). Pegasus 1.2 is retained for backwards compatibility — set modelName="pegasus1.2" only if you need to preserve an existing 1.2 workflow (1.2 is on a deprecation path). This is the right tool when: - You have a URL or local upload, not an indexed videoId. - The video is over 1 hour long (sync analyse is capped at 1h). - You want time-based metadata segmentation (set analysisMode="time_based_metadata" + segmentDefinitions; Pegasus 1.5 only). - You want multimodal prompting: attach up to 4 reference images per segment definition via segmentDefinitions[].mediaSources. For plain prompt Q&A on an already-indexed video, sync-analyse-video is faster (Pegasus 1.2, returns inline). Use that when you already have a videoId. This tool is fire-and-forget: it returns a taskId and status immediately. Poll status with get-analyse-task (every 5-10s; a 2-hour video may take several minutes). When status is "ready", the result lives in the task response. Input rules: - Provide exactly one of videoUrl, assetId, or base64Video. - If using assetId, ensure the asset status is "ready" first (assets still processing will be rejected). - videoUrl must be a direct http(s) link to raw media — YouTube/Drive/Dropbox share links are not accepted. - base64Video max 30 MB encoded; prefer URL or asset for larger inputs. - prompt drives general (prompt-based) analysis on either model. It cannot be combined with analysisMode="time_based_metadata". - analysisMode="time_based_metadata" requires modelName="pegasus1.5" (the default) and segmentDefinitions. - segmentDefinitions requires analysisMode="time_based_metadata" and selects structured per-segment output. - jsonSchema (optional) constrains general-mode output to structured JSON (JSON Schema Draft 2020-12 subset). Cannot be combined with segmentDefinitions. 1.2.4 additions (all optional): - promptV2: structured prompt with <@name> image references (Pegasus 1.5 only). Mutually exclusive with prompt. - startTime / endTime: clip the analysis window to a sub-range (Pegasus 1.5 only). Mutually exclusive with segmentDefinition.timeRanges. - segmentDefinition.timeRanges: restrict TBM extraction to specific time windows. Mutually exclusive with top-level startTime/endTime and min/maxSegmentDuration. - customId: caller-supplied identifier (1-64 chars, [A-Za-z0-9_-]) returned in task responses. Endpoint: https://mcp.twelvelabs.io/mcp - get-analyse-task - Retrieve the status and results of an async analyse task created via async-analyse-video. Call this repeatedly (every 5-10 seconds) after async-analyse-video until status is "ready" or "failed". When status is "ready", the result.data field holds the generated text. In time_based_metadata mode, result.data is a JSON-encoded string keyed by each segmentDefinition id — parse it yourself. Endpoint: https://mcp.twelvelabs.io/mcp - list-analyse-tasks - List async analyse tasks in your account, newest first. Supports pagination and filtering by status, source videoUrl, source assetId, or analysisMode. Returns a compact summary per task — use get-analyse-task for the full result of a specific task. Endpoint: https://mcp.twelvelabs.io/mcp - delete-analyse-task - Delete an async analyse task by ID. Tasks that are still processing cannot be deleted — wait for them to finish or fail, or leave them alone (they expire server-side eventually). Endpoint: https://mcp.twelvelabs.io/mcp ## Resources Not captured ## Prompts - Twelvelabs Onboarding - A prompt to help onboard new users on the twelvelabs platform - Twelvelabs Onboarding - A prompt to help onboard new users on the twelvelabs platform ## Metadata - Owner: io.twelvelabs - Version: 1.0.1 - Runtime: Sse, Streamable Http - Transports: HTTP - License: Not captured - Language: Not captured - Stars: Not captured - Updated: Nov 17, 2025 - Source: https://registry.modelcontextprotocol.io