连接问题
MCP 服务端无法访问
症状：ECONNREFUSED、ETIMEDOUT 或客户端显示 MCP 离线。
修复方案：
- 八爪鱼环境确认地址为
https://mcp.bazhuayu.com；国际 八爪鱼 环境为https://mcp.octoparse.com - 检查公司代理 / 防火墙是否拦截 HTTPS 出站
- URL 末尾不要多余斜杠；协议必须为
https
工具列表为空
症状： MCP 显示已连接，但无search_templates 等工具。
修复方案：
- 断开 MCP 后重新连接并完成授权
- API Key 模式确认 Header 为
x-api-key - 重启客户端（Cursor、Claude Code 等需重启后加载
mcp.json）；Coze / Dify / QClaw 请按平台要求重新保存或重启
响应时间过慢
症状： 单次调用超过 30 秒。 修复方案：- 云采集任务本身耗时较长，可增大
execute_task的timeout - 大任务拆步：先
execute_task，完成后再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 为空。
修复方案：
- 任务可能仍在运行，稍后重试或提高
waitForCompletion/timeout - 在八爪鱼控制台确认任务已成功且有数据
- 确认目标站可从云端访问；部分模板仅支持本地，需换云模板
模板无法通过 MCP 运行
症状： 能search_templates，但 execute_task 失败。
修复方案：
- 选择标注支持云采集的模板
- 本地专用模板请在八爪鱼桌面客户端运行
429 速率限制
症状：429 Too Many Requests。
修复方案：
- 见 速率限制 中的响应头与退避示例
- 避免在短时间内重复调用
search_templates
导出格式错误
症状：export_data 报错。
修复方案：
- 仅支持
json、csv（小写） - 确认任务已有可导出的完成运行
平台相关
| 平台 / 客户端 | 文档 |
|---|---|
| ChatGPT | MCP 对接 ChatGPT |
| Claude | MCP 对接 Claude |
| Cursor | MCP 对接 Cursor |
| VS Code | MCP 对接 VS Code |
| Gemini | MCP 对接 Gemini |
| OpenClaw | MCP 对接 OpenClaw |
| Coze | MCP 对接 Coze |
| Dify | MCP 对接 Dify |
| QClaw | MCP 对接 QClaw |
| OpenClaw | 客户端配置指南 — OpenClaw |
获取帮助
若问题仍未解决，请联系 八爪鱼 支持 或八爪鱼官方客服，并提供：- 失败的 MCP 工具名称与参数（脱敏）
- 完整错误信息或请求 ID
- 使用的 MCP URL 与认证方式（OAuth / API Key）