Skip to main content

​
连接问题

​
MCP 服务端无法访问

症状： ECONNREFUSED、ETIMEDOUT 或客户端显示 MCP 离线。 修复方案：
  • 八爪鱼环境确认地址为 https://mcp.bazhuayu.com；国际 八爪鱼 环境为 https://mcp.octoparse.com
  • 检查公司代理 / 防火墙是否拦截 HTTPS 出站
  • URL 末尾不要多余斜杠；协议必须为 https

​
工具列表为空

症状： MCP 显示已连接，但工具列表为空，或只显示旧的 6 个工具。 修复方案：
  • 断开 MCP 后重新连接并完成授权
  • API Key 模式确认 Header 为 x-api-key
  • 重启客户端（Cursor、Claude Code 等需重启后加载 mcp.json）；Coze / Dify / QClaw 请按平台要求重新保存或重启
  • 连接成功后可用只读工具 list_platforms 验证；当前服务端应公开 10 个工具

​
云任务响应时间较长

症状： execute_task 创建任务后仍未返回最终采集结果。 修复方案：
  • 支持 MCP Tasks 的客户端使用 tasks/get 和 tasks/result 跟踪运行状态
  • 不支持 MCP Tasks 时，取得 accepted 和 taskId 后等待 10-30 秒，再调用 export_data
  • 检查网络到 MCP 节点的延迟

​
授权问题

​
API Key 无效

症状： 401 Unauthorized 或 403 Forbidden。 修复方案：
  • 在 获取 API Key 页面核对创建与配置步骤
  • 在八爪鱼 / 八爪鱼 账户中心重新生成 Key 并更新客户端
  • 确认 Key 未泄露后被作废

​
OAuth 循环或失败

症状： 浏览器反复跳转登录、无法完成授权。 修复方案：
  • 确认登录的是正确的八爪鱼账户
  • 清除浏览器 Cookie 后重新授权
  • 在无界面环境或 OAuth 失败时改用 API Key（见 客户端配置指南）

​
任务执行问题

​
任务未找到

症状： start_or_stop_task 返回 Task not found。 修复方案：
  • 用 search_tasks 确认 taskId
  • 任务须为云采集（MCP 不支持仅本地任务）

​
无数据或导出为空

症状： execute_task 完成但无数据，或 export_data 为空。 修复方案：
  • MCP Tasks 模式先用 tasks/get / tasks/result 确认执行完成；兼容模式等待 10-30 秒后重试 export_data
  • 在八爪鱼控制台确认任务已成功且有数据
  • 确认目标站可从云端访问；部分模板仅支持本地，需换云模板

​
模板无法通过 MCP 运行

症状： 能 search_templates，但 execute_task 失败。 修复方案：
  • 选择标注支持云采集的模板
  • 使用模板精确查询取得 inputSchema，并先调用 execute_task 的 validateOnly: true 模式
  • 检查 canExecuteNow、blockingIssues 和 nextAction；source-backed 字段应传 option key
  • 本地专用模板请在八爪鱼桌面客户端运行

​
429 速率限制

症状： 429 Too Many Requests。 修复方案：
  • 见 速率限制 中的响应头与退避示例
  • 避免在短时间内重复调用 search_templates

​
导出格式错误

症状： export_data 报错。 修复方案：
  • 参数名是 exportFileType，使用大写枚举，例如 JSON、CSV、EXCEL；完整列表见 export_data
  • 确认任务已有可导出的完成运行

​
数据中心平台返回结构变化

症状： list_platforms 的 data 包装层或扩展字段与客户端 Schema 预览不完全一致。 修复方案：
  • 以实际响应中的平台条目为准，只依赖稳定的 platform 和 domain
  • 不要把 platformCode、platformName、sortOrder 或固定包装层作为必需字段
  • 平台目录会动态调整。2026 年 7 月 29 日的只读核验返回 898 个平台条目和 787 个去重域名；该数字仅用于理解当时的目录规模，连接后请重新调用 list_platforms 获取当前结果

​
电商评论暂时为空

症状： ecommerce_data_task 已提交，但短时轮询没有评论。 修复方案：
  • pollReviews 仅每 5 秒查询一次、最多 6 次；达到上限不代表采集失败
  • 稍后使用相同商品 ID 和对应 dataset 调用 query_collected_reviews
  • 检查 Temu 是否已填写 site，以及商品 ID 是否属于所选平台

​
平台相关

​
获取帮助

若问题仍未解决，请联系 八爪鱼 支持 或八爪鱼官方客服，并提供：
  • 失败的 MCP 工具名称与参数（脱敏）
  • 完整错误信息或请求 ID
  • 使用的 MCP URL 与认证方式（OAuth / API Key）
另请参阅：MCP 概览、速率限制