MCP

🚀 Supadata MCP 服务器

Supadata MCP 服务器是一个模型上下文协议（MCP）实现，它与 Supadata 集成，具备视频和网页抓取功能，能有效解决从视频和网页中提取信息的问题，为用户提供便捷的内容获取途径。

✨ 主要特性

• 视频文本提取：支持从 YouTube、TikTok、Twitter 以及文件 URL 中提取视频文本。
• 网页抓取、爬取与发现：可对网页进行抓取、爬取，并发现新的 URL。
• 自动重试与速率限制：具备自动重试机制和速率限制功能，保障服务的稳定性。

你可以在 Smithery 或 MCP.so 的 playground 上体验我们的 MCP 服务器。

📦 安装指南

使用 npx 运行

env SUPADATA_API_KEY=your-api-key npx -y supadata-mcp

手动安装

npm install -g supadata-mcp

在 Cursor 上运行

配置 Cursor 🖥️

注意：需要 Cursor 版本 0.45.6 及以上。 有关最新的配置说明，请参考 Cursor 官方关于配置 MCP 服务器的文档：Cursor MCP 服务器配置指南。

在 Cursor v0.48.6 中配置 Supadata MCP

1. 打开 Cursor 设置。
2. 转到“功能”>“MCP 服务器”。
3. 点击“+ 添加新的全局 MCP 服务器”。
4. 输入以下代码：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

在 Cursor v0.45.6 中配置 Supadata MCP

1. 打开 Cursor 设置。
2. 转到“功能”>“MCP 服务器”。
3. 点击“+ 添加新的 MCP 服务器”。
4. 输入以下信息：
   • 名称：“supadata-mcp”（或你喜欢的名称）
   • 类型：“命令”
   • 命令：env SUPADATA_API_KEY=your-api-key npx -y supadata-mcp

如果你使用的是 Windows 系统且遇到问题，可以尝试 cmd /c "set SUPADATA_API_KEY=your-api-key && npx -y supadata-mcp"。

将 your-api-key 替换为你的 Supadata API 密钥。如果你还没有，可以在 https://www.supadata.dev/app/api-keys 创建账户并获取。

添加后，刷新 MCP 服务器列表以查看新工具。Composer 代理会在合适的时候自动使用 Supadata MCP，但你也可以通过描述网页抓取需求来明确请求使用。通过 Command + L（Mac）访问 Composer，在提交按钮旁边选择“代理”，然后输入你的查询。

在 Windsurf 上运行

将以下内容添加到你的 ./codeium/windsurf/model_config.json 文件中：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Supadata，请运行以下命令：

npx -y @smithery/cli install @supadata-ai/mcp --client claude

在 VS Code 上运行

一键安装

点击以下安装按钮之一：

手动安装

将以下 JSON 块添加到 VS Code 的用户设置（JSON）文件中。你可以通过按下 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 来打开该文件。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Supadata API Key",
        "password": true
      }
    ],
    "servers": {
      "supadata": {
        "command": "npx",
        "args": ["-y", "supadata-mcp"],
        "env": {
          "SUPADATA_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

你也可以选择将其添加到工作区中名为 .vscode/mcp.json 的文件中，这样可以与他人共享配置：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Supadata API Key",
      "password": true
    }
  ],
  "servers": {
    "supadata": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "${input:apiKey}"
      }
    }
  }
}

📚 详细文档

环境变量

• SUPADATA_API_KEY：你的 Supadata API 密钥

与 Claude Desktop 配合使用

将以下内容添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "supadata-mcp": {
      "command": "npx",
      "args": ["-y", "supadata-mcp"],
      "env": {
        "SUPADATA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

系统配置

服务器包含多个可通过环境变量设置的配置参数。如果未进行配置，以下是默认值：

const CONFIG = {
  retry: {
    maxAttempts: 3, // 速率限制请求的重试次数
    initialDelay: 1000, // 首次重试前的初始延迟（毫秒）
    maxDelay: 10000, // 重试之间的最大延迟（毫秒）
    backoffFactor: 2, // 指数退避的乘数
  },
};

速率限制和批量处理

服务器利用 Supadata 内置的速率限制和批量处理功能：

• 自动处理速率限制，采用指数退避策略
• 高效并行处理批量操作
• 智能请求排队和节流
• 对临时错误进行自动重试

🔧 技术细节

如何选择工具

使用以下指南为你的任务选择合适的工具：

• 如果你需要视频内容的文本记录：使用 transcript
• 如果你知道确切的 URL：
  • 单个 URL：使用 scrape
  • 多个 URL：使用 batch_scrape
• 如果你需要发现网站上的 URL：使用 map
• 如果你想分析整个网站或部分内容：使用 crawl（有限制！）

快速参考表

可用工具

1. 文本提取工具 (supadata_transcript)

从支持的视频平台和文件 URL 中提取文本记录。

• 适用场景：分析视频内容并从 YouTube、TikTok、Twitter 和文件 URL 中提取文本记录。
• 不推荐场景：非视频内容（网页使用 scrape 工具）
• 常见错误：对普通网页使用 transcript 工具（应使用 scrape 工具）
• 提示示例：

"从这个 YouTube 视频获取文本记录：https://youtube.com/watch?v=example"

• 使用示例：

{
  "name": "supadata_transcript",
  "arguments": {
    "url": "https://youtube.com/watch?v=example",
    "lang": "en",
    "text": false,
    "mode": "auto"
  }
}

• 返回结果：
  • 文本或格式化输出的文本记录内容
  • 异步处理：用于检查状态的作业 ID

2. 检查文本提取状态 (supadata_check_transcript_status)

检查文本提取作业的状态。

{
  "name": "supadata_check_transcript_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

• 返回结果：包含文本提取作业状态、完成进度和结果的响应。

3. 抓取工具 (supadata_scrape)

使用高级选项从单个 URL 抓取内容。

• 适用场景：当你确切知道包含信息的页面时，提取单页内容。
• 不推荐场景：从多个页面提取内容（已知 URL 使用 batch_scrape，先发现 URL 使用 map + batch_scrape，全面提取使用 crawl）
• 常见错误：对 URL 列表使用 scrape 工具（应使用 batch_scrape 工具）
• 提示示例：

"获取 https://example.com 页面的内容。"

• 使用示例：

{
  "name": "supadata_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "timeout": 30000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}

• 返回结果：指定格式的 Markdown、HTML 或其他内容。

4. 映射工具 (supadata_map)

映射网站以发现网站上所有索引的 URL。

• 适用场景：在决定抓取内容之前发现网站上的 URL，查找网站的特定部分。
• 不推荐场景：当你已经知道确切的 URL 时（使用 scrape 或 batch_scrape），当你需要页面内容时（映射后使用 scrape）
• 常见错误：使用 crawl 发现 URL 而不是 map
• 提示示例：

"列出 example.com 上的所有 URL。"

• 使用示例：

{
  "name": "supadata_map",
  "arguments": {
    "url": "https://example.com"
  }
}

• 返回结果：网站上发现的 URL 数组。

5. 爬取工具 (supadata_crawl)

在网站上启动异步爬取作业并从所有页面提取内容。

• 适用场景：当你需要全面覆盖时，从多个相关页面提取内容。
• 不推荐场景：从单个页面提取内容（使用 scrape），当存在令牌限制时（使用 map + batch_scrape），当你需要快速结果时（爬取可能较慢）
• 警告：爬取响应可能非常大，可能会超过令牌限制。限制爬取深度和页面数量，或使用 map + batch_scrape 以获得更好的控制。
• 常见错误：设置 limit 或 maxDepth 过高（导致令牌溢出），对单个页面使用 crawl（应使用 scrape）
• 提示示例：

"从 example.com/blog 的前两层获取所有博客文章。"

• 使用示例：

{
  "name": "supadata_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

• 返回结果：包含用于检查状态的操作 ID 的响应：

{
  "content": [
    {
      "type": "text",
      "text": "Started crawl for: https://example.com/* with job ID: 550e8400-e29b-41d4-a716-446655440000. Use supadata_check_crawl_status to check progress."
    }
  ],
  "isError": false
}

6. 检查爬取状态 (supadata_check_crawl_status)

检查爬取作业的状态。

{
  "name": "supadata_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

• 返回结果：包含爬取作业状态、完成进度和结果详细信息的响应。

日志系统

服务器包含全面的日志记录：

• 操作状态和进度
• 性能指标
• 信用使用监控
• 速率限制跟踪
• 错误情况

示例日志消息：

[INFO] Supadata MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Batch operation queued with ID: batch_1
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...

错误处理

服务器提供强大的错误处理功能：

• 对临时错误进行自动重试
• 采用退避策略处理速率限制
• 详细的错误消息
• 信用使用警告
• 网络弹性

示例错误响应：

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

贡献代码

1. 分叉仓库
2. 创建你的功能分支
3. 运行测试：npm test
4. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。