CloudGlue MCP Server

Cloudglue MCP 服务

将 Cloudglue 连接到 Cursor、Claude Desktop 和其他 AI 助手，解锁视频集合理解的强大功能。Cloudglue 可帮助将视频转化为适用于大模型的结构化数据。

📖 资源

• Model Context Protocol
• Cloudglue API 文档
• 服务条款
• 隐私政策
• 定价

使用 Cloudglue SDK 和／或 MCP 服务，即表示你同意 Cloudglue 服务条款，并确认已阅读我们的隐私政策。

使用方法

先决条件

首先，从 cloudglue.dev 获取 Cloudglue API 密钥，用于通过你的 Cloudglue 账户对 MCP 服务进行身份验证。

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 密钥。

B. 在 Claude Desktop 上使用 Desktop Extensions

1. 从发布页面下载最新的 Cloudglue Claude Desktop Extension
2. 双击文件以使用 Claude Desktop 打开（此操作前需要先启动 Claude Desktop）
3. 点击“Install”
4. 系统提示时，输入你的 API 密钥
5. 启用扩展

本地开发

先决条件

首先，从 cloudglue.dev 获取 Cloudglue API 密钥，用于通过你的 Cloudglue 账户对 MCP 服务进行身份验证。

构建服务

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 服务支持多种用于视频分析的 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：

  • 会议 UUID：zoom://uuid/QFwZYEreTl2e6MBFSslXjQ%3D%3D
  • 会议 ID：zoom://id/81586198865

工具

以下 Cloudglue 工具可通过此 MCP 服务供大模型使用：

发现与导航

• 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）。分页：使用 page 参数按 5 分钟的片段分页返回结果（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）。结果质量在很大程度上取决于提示词的具体程度。分页：使用 page 参数对片段级实体分页（每页 25 个片段）。每个响应都会以 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 参数（第 0 页 = 前 25 条摘要，第 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
• 发送邮件