> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Integrate Cloudglue's powerful video understanding capabilities directly into Claude Desktop, Cursor, Windsurf, and other AI assistants

> By using the Cloudglue SDK and/or the MCP server, you agree to the [Cloudglue Terms of Service](https://cloudglue.dev/terms) and acknowledge our [Privacy Policy](https://cloudglue.dev/privacy).

<Note>
  The MCP server described on this page gives AI assistants **video
  understanding tools** (transcription, extraction, search). If you're looking
  for an MCP server that feeds Cloudglue **documentation** to your coding agent,
  see the [Docs MCP Server](/getting-started/build-with-ai#docs-mcp-server).
</Note>

## Quick Start

The Cloudglue MCP server lets you connect AI assistants like Claude Desktop, Cursor and Windsurf to Cloudglue's video understanding capabilities through the [Model Context Protocol](https://modelcontextprotocol.io/introduction).

Using the Cloudglue MCP server, you can bring advanced video analysis, transcription, and extraction features directly into your favorite AI chat applications. This allows your AI assistants to understand, analyze, and extract insights from video content without leaving your workflow - whether you're looking to transcribe meetings, extract structured data from video clips, or have conversations about video collections.

The video below walks through how to setup Cloudglue MCP server in a Claude Desktop client

<iframe width="560" height="315" src="https://www.youtube.com/embed/nZSN9b7Yo5o" title="Talking with videos using Cloudglue MCP and Claude Desktop" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Prerequisites

First, get a Cloudglue API Key from [cloudglue.dev](http://cloudglue.dev), this will be used to authenticate the MCP server with your Cloudglue account.

### Node.js

The Filesystem Server and many other MCP servers require Node.js to run. Verify your Node.js installation by opening a terminal or command prompt and running:

```bash theme={null}
node --version
```

If Node.js is not installed, download it from [nodejs.org](https://nodejs.org). We recommend the LTS (Long Term Support) version for stability.

## Setup

### 1. Configure MCP Client

Configure your MCP client (Claude Desktop or Cursor) to use the Cloudglue MCP server:

<Tabs>
  <Tab title="Claude Desktop" value="claude">
    There are three ways to configure the Cloudglue MCP server in Claude Desktop:

    <AccordionGroup>
      <Accordion title="Method 1: Using the Claude Connector Directory (Recommended)" defaultOpen>
        1. Open the [Cloudglue listing in the Claude Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.cloudglue.cloudglue-mcp)
        2. Click **Install** (you'll need to be signed into claude.ai)
        3. When prompted, paste your [Cloudglue API key](https://app.cloudglue.dev/home/api-keys)
        4. The connector is now available in Claude Desktop — no Node.js install or config editing required
      </Accordion>

      <Accordion title="Method 2: Using Claude Desktop Extension">
        1. Download the latest Cloudglue Claude Desktop Extension from [the releases page](https://github.com/cloudglue/cloudglue-mcp-server/releases/latest/download/cloudglue-mcp-server.mcpb)
        2. Double click to open with Claude Desktop (you need to have Claude Desktop running prior to this)
        3. Click 'Install'
        4. When prompted, enter your API key
        5. Enable the extension
      </Accordion>

      <Accordion title="Method 3: Using manual configuration">
        1. Open the Claude menu on your computer and select "Settings..."
        2. Click on "Developer" in the left-hand bar of the Settings pane
        3. Click on "Edit Config"

        This will open your `claude_desktop_config.json` file (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows).

        Add the following configuration to the file:

        ```json theme={null}
        {
          "mcpServers": {
            "cloudglue": {
              "command": "npx",
              "args": [
                "-y",
                "@cloudglue/cloudglue-mcp-server@latest",
                "--api-key",
                "<CLOUDGLUE-YOUR-API-KEY>"
              ]
            }
          }
        }
        ```

        Replace `<CLOUDGLUE-YOUR-API-KEY>` with your Cloudglue API key.

        After updating the configuration, restart Claude Desktop completely.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Cursor" value="cursor">
    Cursor provides a UI for adding MCP servers (requires Cursor version 0.45.6+):

    1. Open Cursor Settings
    2. Go to Features > MCP Servers
    3. Click "+ Add new global MCP server"
    4. Enter the following configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "cloudglue": {
          "command": "npx",
          "args": [
            "-y",
            "@cloudglue/cloudglue-mcp-server@latest",
            "--api-key",
            "<CLOUDGLUE-YOUR-API-KEY>"
          ]
        }
      }
    }
    ```

    Replace `<CLOUDGLUE-YOUR-API-KEY>` with your Cloudglue API key.

    Alternatively, you can add a project-specific configuration by creating a `.cursor/mcp.json` file in your project directory, or a global configuration by creating a `~/.cursor/mcp.json` file in your home directory.
  </Tab>
</Tabs>

### 2. Verify Installation

Once configured:

* **In Claude Desktop**: You should see a slider icon in the bottom left corner of the input box. Click it to see the available Cloudglue tools.
* **In Cursor**: The Agent will automatically detect and use relevant Cloudglue tools when needed.

## Remote MCP Server

Cloudglue also provides a remote MCP server that you can connect to directly without installing the local package.

### Transport Options

The remote server supports two transport types:

#### **Server-Sent Events (SSE)**

* **URL**: `https://mcp.cloudglue.dev/sse`
* **Authentication**:
  * Header Name: `Authorization`
  * Bearer Token: Your Cloudglue API Key

#### **Streamable HTTP**

* **URL**: `https://mcp.cloudglue.dev/mcp`
* **Authentication**:
  * Header Name: `Authorization`
  * Bearer Token: Your Cloudglue API Key

### Cursor Configuration

For Cursor, you can use the remote server with this configuration:

```json theme={null}
{
  "mcpServers": {
    "cloudglue-remote": {
      "url": "https://mcp.cloudglue.dev/mcp",
      "headers": {
        "Authorization": "Bearer <CLOUDGLUE-API-KEY>"
      }
    }
  }
}
```

### Local Proxy Workaround

Since all MCP clients do not fully support remote MCP servers yet, you can use this proxy configuration:

```json theme={null}
{
  "mcpServers": {
    "cloudglue-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.cloudglue.dev/mcp",
        "--header",
        "Authorization: Bearer <CLOUDGLUE-API-KEY>"
      ]
    }
  }
}
```

> **Note**: OAuth-based authentication is coming soon to simplify the setup process and eliminate the need to manually manage API keys in configurations.

## Supported URL Formats

The Cloudglue MCP Server supports multiple URL formats for video analysis:

### **Cloudglue Platform (Default)**

* **Format**: `cloudglue://files/file-id`
* **Usage**: Use file ID from `list_videos` tool
* **Best for**: Videos already uploaded to Cloudglue

### **YouTube URLs**

* **Formats**:
  * `https://www.youtube.com/watch?v=...`
  * `https://youtu.be/...`
* **Supported tools**: `describe_video`, `extract_video_entities`, `segment_video_chapters`
* **Note**: Not supported for `segment_video_camera_shots`

### **Public HTTP Video URLs**

* **Format**: Direct links to MP4 files (e.g., `https://example.com/video.mp4`)
* **Best for**: Publicly accessible video files

### **Data Connector URLs**

*Requires setup in Cloudglue account - see [Data Connectors Documentation](https://docs.cloudglue.dev/data-connectors/overview)*

* **Dropbox**:
  * Shareable links: `https://www.dropbox.com/scl/fo/SOME_ID/SOME_OTHER_ID?rlkey=SOME_KEY&st=SOME_TIME&dl=0`
  * Direct path: `dropbox://<path>/<to>/<file>`

* **Google Drive**:
  * Format: `gdrive://file/<file_id>`

* **Zoom**:
  * Meeting UUID: `zoom://uuid/QFwZYEreTl2e6MBFSslXjQ%3D%3D`
  * Meeting ID: `zoom://id/81586198865`

## Available Tools

Once configured, your AI assistant can access the following Cloudglue tools:

### Discovery & Navigation

* **`list_collections`**: Discover available video collections and their basic metadata. Use this first to understand what video collections exist before using other collection-specific tools. Shows collection IDs needed for other tools, video counts, and collection types. **Pagination guidance**: For comprehensive exploration, paginate through all collections (check has\_more and increment offset by limit) to ensure you don't miss any collections. Use smaller limits (5-10) for quick overviews, larger limits (25-50) for thorough exploration.

* **`list_videos`**: Browse and search video metadata with powerful filtering options. Use this to explore available videos, find specific content by date, or see what's in a collection. Returns essential video info like duration, filename, and IDs needed for other tools. **Pagination guidance**: For exhaustive exploration, paginate through all videos (check has\_more and increment offset by limit) to ensure complete coverage. Use date filtering to focus on specific time periods, then paginate within those results.

### Individual Video Analysis

* **`describe_video`**: Get comprehensive transcripts and descriptions from individual videos with intelligent cost optimization. Automatically checks for existing transcripts before creating new ones. Use this for individual video analysis - for analyzing multiple videos in a collection, use retrieve\_collection\_descriptions instead. Supports all URL formats: Cloudglue URLs, YouTube URLs, public HTTP video URLs, and data connector URLs (Dropbox, Google Drive, Zoom).

* **`extract_video_entities`**: Extract structured data and entities from videos using custom prompts with intelligent cost optimization. Automatically checks for existing extractions before creating new ones. Use this for individual video analysis - for analyzing multiple videos in a collection, use retrieve\_collection\_entities instead. Supports all URL formats: Cloudglue URLs, YouTube URLs, public HTTP video URLs, and data connector URLs (Dropbox, Google Drive, Zoom). The quality of results depends heavily on your prompt specificity.

* **`get_video_metadata`**: Get comprehensive technical metadata about a Cloudglue video file including duration, resolution, file size, processing status, and computed statistics. Use this when you need video specifications, file details, or processing information rather than content analysis. Different from content-focused tools like describe\_video.

* **`segment_video_camera_shots`**: Segment videos into camera shots with intelligent cost optimization. Automatically checks for existing shot segmentation jobs before creating new ones. Returns timestamps and metadata for each camera shot detected. Supports Cloudglue URLs, public HTTP video URLs, and data connector URLs (Dropbox, Google Drive, Zoom). Note: YouTube URLs are not supported for camera shot segmentation.

* **`segment_video_chapters`**: Segment videos into chapters with intelligent cost optimization. Automatically checks for existing chapter segmentation jobs before creating new ones. Returns timestamps and descriptions for each chapter detected. Supports all URL formats: Cloudglue URLs, YouTube URLs, public HTTP video URLs, and data connector URLs (Dropbox, Google Drive, Zoom).

### Collection Analysis

* **`retrieve_summaries`**: Bulk retrieve video summaries and titles from a collection to quickly understand its content and themes. Works with both rich-transcripts and media-descriptions collections. Perfect for getting a high-level overview of what's in a collection, identifying common topics, or determining if a collection contains relevant content for a specific query. Use this as your first step when analyzing a collection - it's more efficient than retrieving full descriptions and helps you determine if you need more detailed information. Only proceed to retrieve\_descriptions if you need the full multimodal context for specific videos identified through the summaries. For targeted content discovery, consider using search\_video\_summaries or search\_video\_moments instead of browsing through all summaries. **Pagination guidance**: For comprehensive collection analysis, paginate through all summaries (check has\_more and increment offset by limit) to ensure complete coverage. Use larger limits (25-50) for efficient bulk analysis, smaller limits (5-10) for targeted exploration.

* **`retrieve_descriptions`**: Bulk retrieve rich multimodal descriptions (text, audio, and visual) from a collection with advanced filtering. Works with both rich-transcripts and media-descriptions collections. Use this only after using retrieve\_summaries to identify specific videos that need detailed analysis. This tool is more resource-intensive and limited to 10 descriptions per request, so it's best used for targeted analysis of specific videos rather than broad collection overview. For single videos, use describe\_video instead. Use date filtering to focus on specific time periods. For targeted content discovery, consider using search\_video\_moments or search\_video\_summaries instead of parsing through dense full descriptions. **Pagination guidance**: Due to the 10-item limit, pagination is essential for comprehensive analysis. Always check has\_more and paginate through all descriptions when user intent requires exhaustive coverage. Use date filtering first to narrow scope, then paginate within filtered results.

* **`retrieve_entities`**: Batch retrieve structured entity data from multiple videos in a collection. Entities can be user-defined based on what's important for your collection (people, objects, concepts, custom categories). Perfect for data mining, building datasets, or analyzing previously extracted entities at scale. **Pagination guidance**: For comprehensive entity analysis, paginate through all entities (check has\_more and increment offset by limit) to ensure complete data coverage. Use date filtering to focus on specific time periods, then paginate within those results. Essential for building complete datasets or performing exhaustive entity analysis.

* **`search_video_moments`**: AI-powered semantic search to find specific video segments within a collection. Uses Cloudglue's search API to locate relevant moments across speech, on-screen text, and visual descriptions. Returns structured search results with timestamps and metadata. Perfect for finding needle-in-haystack spoken and visual content, specific discussions, or thematic analysis.

* **`search_video_summaries`**: AI-powered semantic search to find relevant videos within a collection. Uses Cloudglue's search API to locate videos based on their content, summaries, and metadata. Works with rich-transcripts and media-descriptions collections. Returns structured search results with video information and relevance scores. Perfect for discovering videos by topic, theme, or content similarity.

## Pagination Strategy

### When to Paginate Exhaustively

* User asks for "all" or "complete" analysis of collections/videos
* User wants comprehensive coverage or exhaustive exploration
* User requests data mining, dataset building, or complete entity extraction
* User asks for "everything" in a collection or time period

### How to Paginate

1. Start with initial request (offset=0, appropriate limit)
2. Check response `pagination.has_more` field
3. If `has_more: true`, increment offset by limit and repeat
4. Continue until `has_more: false` or you have sufficient data
5. Use date filtering first to narrow scope, then paginate within results

### Limit Guidelines

* **Quick overviews**: 5-10 items
* **Comprehensive analysis**: 25-50 items
* **Exhaustive exploration**: Use maximum limits (50 for summaries, 10 for descriptions/entities)

### When to Use Which Tool

* **Start exploring**: Use `list_collections` and `list_videos` to explore available content
* **For single videos**: Use `describe_video`, `extract_video_entities`, `segment_video_camera_shots`, or `segment_video_chapters`
* **For collection overview**: Always start with `retrieve_summaries` to efficiently understand what's in a collection
* **For detailed analysis**: Only use `retrieve_descriptions` for specific videos that need full multimodal context, identified through summaries
* **For structured data**: Use `retrieve_entities` for bulk entity extraction
* **For specific content**: Use `search_video_moments` for targeted segment search, `search_video_summaries` for video-level search
* **For technical specs**: Use `get_video_metadata`

All tools include intelligent features like cost optimization, automatic fallbacks, and comprehensive error handling.

## Troubleshooting

If the MCP server isn't working:

1. Ensure you have Node.js installed (`node --version` in terminal)
2. Verify your API key is correct
3. Restart the client application completely
4. Check logs for any error messages

## Resources

* [Official Cloudglue MCP Server NPM Package](https://www.npmjs.com/package/@cloudglue/cloudglue-mcp-server)
* [Cloudglue API Docs](https://docs.cloudglue.dev)
* [Model Context Protocol](https://modelcontextprotocol.io/introduction)
* [Claude Desktop MCP Guide](https://modelcontextprotocol.io/quickstart/user)
* [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol)

## Contact

* [Open an Issue](https://github.com/cloudglue/cloudglue-mcp-server/issues/new)
* [Email](mailto:support@cloudglue.dev)