TwelveLabs MCP Server

Overview

The TwelveLabs MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with the TwelveLabs platform. This server enables AI assistants and applications to interact with TwelveLabs powerful video analysis capabilities through a standardized MCP interface.

What it does

This server provides tools for:

• Video Index Management: Create, list, and delete video indexes for organizing video content
• Video Indexing: Upload and index videos to make them searchable and analyzable
• Video Search: Search through indexed videos using natural language queries
• Video Analysis: Generate titles, topics, hashtags, summaries, chapters, and highlights from videos
• Video Embeddings: Create and retrieve video embeddings for advanced AI applications

Key Features

• Natural Language Search: Search videos using descriptive queries that understand visual elements, actions, sounds, and on-screen text
• AI-Powered Analysis: Generate comprehensive video insights including summaries, chapters, and highlights
• Flexible Indexing: Support for both generative and embedding models
• Task Management: Monitor and track video processing tasks
• Default Index Handling: Automatic creation and management of default indexes

Available Prompts

Twelvelabs Onboarding

A prompt that helps new user onboard on the TwelveLabs Platform

Available Tools

Index Management

create-index

Create a new TwelveLabs video index for organizing and storing video data.

Parameters:

• name (string, required): Name of the index
• models (array, optional): Type of models to use. Options: ["generative", "embedding"]. Defaults to both models if not specified.

list-indexes

List all available TwelveLabs video indexes.

Parameters: None

delete-index

Delete a TwelveLabs video index.

Parameters:

• indexId (string, required): ID of the index to delete

Video Indexing

get-sample-videos

Get a curated list of open-source sample videos that can be used to test the TwelveLabs platform features.

Parameters: None

Returns: A list of sample videos with titles, descriptions, URLs, and duration information.

start-video-indexing-task

Start indexing a video to make it searchable and analyzable. Supports both remote URLs and local file uploads.

Parameters:

• videoUrl (string, optional): URL of the video to index
• videoFilePath (string, optional): Absolute path to a local video file to upload (e.g., /path/to/video.mp4). Only available with stdio transport (twelvelabs-mcp-stdio).
• indexId (string, optional): ID of the index. If not provided, uses the default index.

Note: Provide either videoUrl or videoFilePath. If both are provided, videoUrl takes precedence.

get-video-indexing-tasks-status

Get the status of video indexing tasks.

Parameters:

• taskId (string, optional): ID of the specific task. If not provided, returns status of the latest 10 tasks.

Possible Statuses:

• Validating: Video upload complete, API validating requirements
• Pending: Platform spawning worker server
• Queued: Worker assigned, preparing to index
• Indexing: Transforming video into embeddings
• Ready: Indexing complete
• Failed: Indexing failed

list-videos

List all videos in a video index.

Parameters:

• indexId (string, optional): ID of the index. If not provided, uses the default index.

Video Search

search

Search through indexed videos using natural language descriptions.

Parameters:

• query (string, required): Natural language search query
• indexId (string, optional): ID of the index to search. If not provided, searches the default index.

Video Analysis

analyse-video

Analyze a video to generate various types of content and insights.

Parameters:

• videoId (string, required): ID of the video to analyze
• type (string, required): Type of analysis. Options:
  • title: Generate video title
  • topic: Generate video topics
  • hashtag: Generate relevant hashtags
  • summary: Generate video summary
  • chapter: Generate video chapters with timestamps
  • highlight: Generate video highlights
  • open-ended: Custom analysis based on prompt
• prompt (string, optional): Custom prompt to guide the analysis (max 2000 tokens). Required for open-ended analysis.

Video Embeddings

start-video-embeddings-task

Start creating video embeddings for a video.

Parameters:

• videoUrl (string, required): URL of the video

get-video-embeddings-tasks-status

Get the status of video embeddings tasks.

Parameters:

• taskId (string, optional): ID of the specific task. If not provided, returns status of the latest 10 tasks.

Possible Statuses:

• processing: Task is being processed
• ready: Task completed successfully
• failed: Task failed

retrieve-video-embeddings

Retrieve video embeddings from a completed embedding task or an indexed video.

Parameters:

• taskId (string, optional): ID of the video embeddings task. If provided, indexId & videoId are ignored.
• indexId (string, optional): ID of the index containing the video. If not provided we will try to use the default index if it exists.
• videoId (string, optional): ID of the video to retrieve.

Prerequisites

• Node.js 18+
• A TwelveLabs API key (to be passed in headers by the MCP client - Support verified for Claude Desktop, Cursor & Goose for now)

Environment Variables

The following environment variables can be configured:

• TWELVE_LABS_API_KEY (required): Your TwelveLabs API key
• MCP_HTTP_PORT (optional): Port for the MCP server (default: 3000)

Installation

1. Clone the repository:

git clone <repository-url>
cd twelvelabs-mcp

2. Install dependencies:

npm install

Usage

Development

Start the development server with hot-reload:

npm run dev

The server will start on http://localhost:3000 and automatically restart when you make changes to the source code.

Production Build

Build the project for production:

npm run build

The compiled JavaScript will be output to the dist/ directory.

Running the Inspector

Use the MCP inspector tool to test your server:

npm run inspector

Using with Claude Code (stdio transport)

For CLI tools like Claude Code that use stdio transport, use twelvelabs-mcp-stdio:

npx twelvelabs-mcp-stdio

Configure in your MCP settings (e.g., .mcp.json):

{
  "mcpServers": {
    "twelvelabs-mcp": {
      "command": "npx",
      "args": ["twelvelabs-mcp-stdio"],
      "env": {
        "TWELVELABS_API_KEY": "your-api-key"
      }
    }
  }
}

API Endpoints

• POST /mcp - Main MCP communication endpoint
• GET /mcp - Returns "Method not allowed" (405)
• DELETE /mcp - Returns "Method not allowed" (405)