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
• 电子邮件