Cloudglue MCP Server

🎥 Cloudglue MCP Server

將 Cloudglue 連接到 Cursor、Claude Desktop 和其他 AI 助手，釋放視頻集合理解的能力。Cloudglue 幫助你將視頻轉化為可供 LLM 使用的結構化數據。

📖 資源

• 模型上下文協議 (MCP)
• Cloudglue API 文檔
• 服務條款
• 隱私政策
• 定價

使用 Cloudglue SDK 和/或 MCP 服務器，即表示你同意 Cloudglue 服務條款 並確認我們的 隱私政策。

🚀 使用方法

📋 前置條件

首先，從 cloudglue.dev 獲取 Cloudglue API Key，它將用於 MCP 服務器與你的 Cloudglue 賬戶進行身份驗證。

A. 在任意使用 JSON 配置的 MCP 客戶端上

大多數 MCP 客戶端將配置存儲為 JSON。對於 cloudglue-mcp-server，配置如下：

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

將 <CLOUDGLUE-YOUR-API-KEY> 替換為之前創建的 API Key。

B. 在 Claude Desktop 上使用桌面擴展

1. 從 releases 頁面 下載最新的 Cloudglue Claude Desktop Extension
2. 雙擊用 Claude Desktop 打開（你需要提前運行 Claude Desktop）
3. 點擊 “Install”
4. 彈出提示時，輸入你的 API key
5. 啟用該擴展

🛠️ 本地開發

📋 前置條件

首先，從 cloudglue.dev 獲取 Cloudglue API Key，它將用於 MCP 服務器與你的 Cloudglue 賬戶進行身份驗證。

🏗️ 構建服務器

1. 克隆倉庫
2. 使用 npm install 安裝依賴
3. 使用 npm build 構建服務器 + Claude Desktop Extension

⚙️ 配置 MCP 客戶端

接下來，配置你的 MCP 客戶端（例如 Cursor）以使用此服務器。大多數 MCP 客戶端將配置以 JSON 格式存儲如下：

{
  "mcpServers": {
    "cloudglue-mcp-server": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/cloudglue-mcp-server/build/index.js",
        "--api-key",
        "<CLOUDGLUE-YOUR-API-KEY>"
      ]
    }
  }
}

📚 文檔

🌐 支持的 URL 格式

Cloudglue MCP Server 支持多種用於視頻分析的 URL 格式：

Cloudglue 平臺（默認）

• 格式：cloudglue://files/file-id
• 用法：使用 list_videos 工具中的文件 ID
• 最適合：已上傳到 Cloudglue 的視頻

YouTube URL

• 格式：
  • https://www.youtube.com/watch?v=...
  • https://youtu.be/...
• 支持的工具：describe_video、extract_video_entities、segment_video_chapters
• 注意：不支持 segment_video_camera_shots

公共 HTTP 視頻 URL

• 格式：直接鏈接到 MP4 文件（例如 https://example.com/video.mp4）
• 最適合：可公開訪問的視頻文件

數據連接器 URL

需要在 Cloudglue 賬戶中設置 - 參見 數據連接器文檔

• Dropbox：
  • 可分享鏈接：https://www.dropbox.com/scl/fo/SOME_ID/SOME_OTHER_ID?rlkey=SOME_KEY&st=SOME_TIME&dl=0
  • 直接路徑：dropbox://<path>/<to>/<file>
• Google Drive：
  • 格式：gdrive://file/<file_id>
• Zoom：
  • Meeting UUID：zoom://uuid/QFwZYEreTl2e6MBFSslXjQ%3D%3D
  • Meeting ID：zoom://id/81586198865

🧰 工具

以下 Cloudglue 工具可通過此 MCP 服務器供 LLM 使用：

發現與導航

• list_collections：發現可用的視頻集合並獲取其基本元數據。先使用此工具瞭解存在哪些視頻集合，再使用其他集合相關工具。顯示其他工具所需的集合 ID、視頻數量和集合類型。對於類型為 'media-descriptions' 的集合，使用帶 collection_id 參數的 describe_video 來獲取指定 Cloudglue 文件之前已提取的描述。對於類型為 'entities' 的集合，使用帶 collection_id 參數的 extract_video_entities 來獲取指定 Cloudglue 文件之前已提取的實體。分頁：結果每頁 25 個集合，使用 page 參數（page 0 = 前 25 個集合，page 1 = 接下來 25 個集合，依此類推）。每個響應包含 page 和 total_pages 字段。要進行全面探索，請遞增 page 參數並翻頁瀏覽所有集合，直到檢索完所有頁面。

• list_videos：通過強大的過濾選項瀏覽和搜索視頻元數據。使用此工具探索可用視頻、按日期查找特定內容，或查看集合中的內容。返回其他工具所需的關鍵視頻信息，如時長、文件名和 ID。分頁：結果每頁 25 個視頻，使用 page 參數（page 0 = 前 25 個視頻，page 1 = 接下來 25 個視頻，依此類推）。每個響應包含 page 和 total_pages 字段。使用日期過濾聚焦特定時間段，然後在這些結果中分頁。

單個視頻分析

• describe_video：從單個視頻獲取全面的轉錄和描述，支持智能成本優化和分頁。在創建新轉錄前會自動檢查是否已有轉錄。支持所有 URL 格式：Cloudglue URL、YouTube URL、公共 HTTP 視頻 URL，以及數據連接器 URL（Dropbox、Google Drive、Zoom）。分頁：結果以 5 分鐘為一段進行分頁，使用 page 參數（page 0 = 前 5 分鐘，page 1 = 接下來 5 分鐘，依此類推）。使用 start_time_seconds 從指定時間索引開始分頁（默認為 0）。與 page 結合可實現精確定位：start_time_seconds 設置基準偏移，page 從該偏移開始以 5 分鐘為段遞增（例如，start_time_seconds=600 且 page=0 返回 10-15 分鐘，page=1 返回 15-20 分鐘）。每個響應以 JSON 格式包含 page、total_pages 和 description 字段。使用分頁可高效處理較長視頻，通過可管理的塊檢索描述，或定位特定時間範圍。分頁對集合描述（使用 collection_id 時）和單個視頻描述均一致有效。

• extract_video_entities：使用自定義提示詞從視頻中提取結構化數據和實體，支持智能成本優化和分頁。在創建新提取前會自動檢查是否已有提取。支持所有 URL 格式：Cloudglue URL、YouTube URL、公共 HTTP 視頻 URL，以及數據連接器 URL（Dropbox、Google Drive、Zoom）。結果質量在很大程度上取決於提示詞的具體程度。分頁：片段級實體分頁（每頁 25 個片段），使用 page 參數。每個響應以 JSON 格式包含 video_level_entities 和 segment_level_entities，以及 entities、page 和 total_pages 字段。

• get_video_metadata：獲取 Cloudglue 視頻文件的全面技術元數據，包括時長、分辨率、文件大小、處理狀態和計算統計信息。返回結構化 JSON 結果，包含完整文件元數據、視頻信息（分辨率、fps、編解碼器等）、處理時間戳和計算字段。當你需要視頻規格、文件詳情或處理信息而非內容分析時使用此工具。它不同於 describe_video 等以內容為中心的工具。

• segment_video_camera_shots：通過智能成本優化將視頻分割為鏡頭。在創建新鏡頭分割任務前會自動檢查是否已有任務。返回結構化 JSON 結果，其中 segments 數組包含檢測到的每個鏡頭的時戳、格式化時間和時長。支持 Cloudglue URL、公共 HTTP 視頻 URL 和數據連接器 URL（Dropbox、Google Drive、Zoom）。注意：YouTube URL 不支持鏡頭分割。

• segment_video_chapters：通過智能成本優化將視頻分割為章節。在創建新章節分割任務前會自動檢查是否已有任務。返回結構化 JSON 結果，其中 chapters 數組包含檢測到的每個章節的時戳、格式化時間和描述。支持可選的自定義提示詞參數以引導章節檢測。支持所有 URL 格式：Cloudglue URL、YouTube URL、公共 HTTP 視頻 URL 和數據連接器 URL（Dropbox、Google Drive、Zoom）。

集合分析

• retrieve_summaries：從集合中批量檢索視頻摘要和標題，以快速理解其內容和主題。適用於 rich-transcripts 和 media-descriptions 集合。非常適合獲取集合內容的高層概覽、識別常見主題，或判斷集合是否包含特定查詢的相關內容。在分析集合時，將此作為第一步 —— 它比檢索完整描述更高效，並幫助你判斷是否需要更詳細的信息。若要進行有針對性的內容發現，考慮使用 search_video_summaries 或 search_video_moments，而不是瀏覽所有摘要。分頁：結果每頁 25 條摘要，使用 page 參數（page 0 = 前 25 條摘要，page 1 = 接下來 25 條摘要，依此類推）。每個響應包含 page 和 total_pages 字段。要進行全面的集合分析，請遞增 page 參數並翻頁瀏覽所有摘要，直到檢索完所有頁面。

• search_video_moments：AI 驅動的語義搜索，用於在集合中查找特定視頻片段。使用 Cloudglue 的搜索 API 定位跨語音、屏幕文本和視覺描述的相關時刻。返回帶時戳和元數據的結構化搜索結果。非常適合大海撈針式地查找語音和視覺內容、特定討論或進行主題分析。每個查詢最多返回 20 個相關視頻片段。

• search_video_summaries：AI 驅動的語義搜索，用於在集合中查找相關視頻。使用 Cloudglue 的搜索 API 根據視頻內容、摘要和元數據定位視頻。適用於 rich-transcripts 和 media-descriptions 集合。返回帶視頻信息和相關性分數的結構化搜索結果。非常適合按主題、話題或內容相似性發現視頻。每個查詢最多返回 20 個相關視頻。

分頁策略

何時需要窮盡分頁：

• 用戶要求對集合/視頻進行“全部”或“完整”分析
• 用戶想要全面覆蓋或窮盡探索
• 用戶請求數據挖掘、數據集構建或完整實體提取
• 用戶要求集合或時間段中的“所有內容”

如何分頁：

所有工具都使用基於頁面的分頁（list_collections、list_videos、describe_video、extract_video_entities、retrieve_summaries）：

1. 從初始請求開始（page=0）
2. 檢查響應中的 total_pages 字段
3. 如果 page < total_pages - 1，遞增 page 並重復
4. 繼續直到檢索完所有頁面或獲得足夠數據

各工具頁面大小：

• list_collections：每頁 25 個集合
• list_videos：每頁 25 個視頻
• describe_video：每頁 5 分鐘
• extract_video_entities：每頁 25 個片段實體
• retrieve_summaries：每頁 25 條摘要

何時使用哪個工具

• 開始探索：使用 list_collections 和 list_videos 探索可用內容
• 單個視頻：使用 describe_video、extract_video_entities、segment_video_camera_shots 或 segment_video_chapters
• 集合概覽：始終先使用 retrieve_summaries，以高效瞭解集合內容
• 詳細分析：對通過摘要識別出的需要完整多模態上下文的特定視頻，使用 describe_video
• 結構化數據：使用 extract_video_entities 從單個視頻中提取實體
• 特定內容：使用 search_video_moments 進行定位片段搜索，使用 search_video_summaries 進行視頻級搜索
• 技術規格：使用 get_video_metadata

所有工具都包含智能功能，如成本優化、自動回退和全面的錯誤處理。

📞 聯繫方式

• 提交 Issue
• 電子郵件