> ## Documentation Index
> Fetch the complete documentation index at: https://www.bazhuayu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 故障排查

> 针对常见连接、授权及任务相关问题的修复方案。

## 连接问题

### 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](/docs/zh/mcp/quick-start/api-key) 页面核对创建与配置步骤
* 在八爪鱼 / 八爪鱼 账户中心重新生成 Key 并更新客户端
* 确认 Key 未泄露后被作废

### OAuth 循环或失败

**症状：** 浏览器反复跳转登录、无法完成授权。

**修复方案：**

* 确认登录的是正确的八爪鱼账户
* 清除浏览器 Cookie 后重新授权
* 在无界面环境或 OAuth 失败时改用 **API Key**（见 [客户端配置指南](/docs/zh/mcp/guides/clients)）

## 任务执行问题

### 任务未找到

**症状：** `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`。

**修复方案：**

* 见 [速率限制](/docs/zh/mcp/rate-limits) 中的响应头与退避示例
* 避免在短时间内重复调用 `search_templates`

### 导出格式错误

**症状：** `export_data` 报错。

**修复方案：**

* 参数名是 `exportFileType`，使用大写枚举，例如 `JSON`、`CSV`、`EXCEL`；完整列表见 [`export_data`](/docs/zh/mcp/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 是否属于所选平台

## 平台相关

| 平台 / 客户端 | 文档                                                    |
| -------- | ----------------------------------------------------- |
| ChatGPT  | [MCP 对接 ChatGPT](/docs/zh/mcp/integrations/chatgpt)        |
| Claude   | [MCP 对接 Claude](/docs/zh/mcp/integrations/claude)          |
| Cursor   | [MCP 对接 Cursor](/docs/zh/mcp/integrations/cursor)          |
| VS Code  | [MCP 对接 VS Code](/docs/zh/mcp/integrations/vscode)         |
| Gemini   | [MCP 对接 Gemini](/docs/zh/mcp/integrations/gemini)          |
| OpenClaw | [MCP 对接 OpenClaw](/docs/zh/mcp/integrations/openclaw)      |
| Coze     | [MCP 对接 Coze](/docs/zh/mcp/integrations/coze)              |
| Dify     | [MCP 对接 Dify](/docs/zh/mcp/integrations/dify)              |
| QClaw    | [MCP 对接 QClaw](/docs/zh/mcp/integrations/qclaw)            |
| OpenClaw | [客户端配置指南 — OpenClaw](/docs/zh/mcp/guides/clients#openclaw) |

## 获取帮助

若问题仍未解决，请联系 [八爪鱼 支持](mailto:support@octoparse.com) 或八爪鱼官方客服，并提供：

* 失败的 MCP 工具名称与参数（脱敏）
* 完整错误信息或请求 ID
* 使用的 MCP URL 与认证方式（OAuth / API Key）

另请参阅：[MCP 概览](/docs/zh/mcp/index)、[速率限制](/docs/zh/mcp/rate-limits)