MCP 故障排除

本指南帮助你解决使用 Browserman 与模型上下文协议（MCP）时的常见问题。

连接问题

MCP 服务器无响应

症状：

• AI 助手说"无法连接到 Browserman MCP 服务器"
• 超时错误
• 工具无响应

解决方案：

1. 验证服务器 URL 和 API 密钥

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   确保没有拼写错误或额外字符。

2. 检查互联网连接

   • 确保你有稳定的互联网连接
   • 尝试在浏览器中访问 https://mcp.browserman.run

3. 重启 MCP 客户端

   • Claude Code：无需重启，更改立即生效
   • Cursor/Codex：关闭并重新打开应用程序
   • Claude Desktop：完全关闭并重新打开

身份验证失败

症状：

• "身份验证失败"错误
• "无效的 API 密钥"消息
• 401 未授权响应

解决方案：

1. 验证 API 密钥格式

   正确的 header 是 X-API-Key：

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   • X-API-Key 不需要"Bearer "前缀
   • 检查额外的空格或换行符
   • 验证密钥未过期

2. 生成新 API 密钥

   • 访问 app.browserman.run
   • 在侧边栏点击 API 密钥
   • 点击 + 新建密钥
   • 生成新密钥
   • 更新配置

工具执行问题

"找不到账号"错误

症状：

错误：未找到平台 'twitter' 的账号 'account-name'

解决方案：

1. 列出可用账号 询问 AI 助手："显示我所有连接的账号"

2. 验证账号名称

   • 账号名称区分大小写
   • 检查拼写错误或额外空格
   • 使用账号列表中的确切名称

3. 绑定账号

   • 访问 app.browserman.run
   • 前往账号 > 添加账号
   • 遵循账号绑定指南

任务超时错误

症状：

• "任务执行超时"错误
• 长时间运行的任务永不完成
• 几分钟后无响应

解决方案：

1. 增加超时设置

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY"
         },
         "timeout": 300000
       }
     }
   }

   注意：超时以毫秒为单位（300000 = 5 分钟）

2. 对复杂任务使用完整模式 为需要更多处理时间的任务指定 preferredEngine: "full"。

配置问题

找不到配置文件

症状：

• AI 助手无法识别 Browserman 工具
• 配置更改不生效

解决方案：

1. 找到正确的配置文件

   Claude Code（推荐）：

   • 使用 CLI 命令：claude mcp add --transport http browserman https://mcp.browserman.run --header "X-API-Key: YOUR_KEY"
   • 验证：claude mcp list

   Cursor：

   • macOS/Linux：~/.cursor/mcp.json
   • Windows：%USERPROFILE%\.cursor\mcp.json

   Claude Desktop：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 验证 JSON 语法 使用 JSON 验证器检查配置：

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY"
         }
       }
     }
   }

更改不生效

解决方案：

1. 重启应用程序

   • Claude Code：更改立即生效，无需重启
   • Cursor/Codex：重启应用程序
   • Claude Desktop：更改后必须重启

2. 检查文件权限 确保配置文件可读

获取帮助

联系支持前

1. 收集信息

   • 失败任务的任务 ID
   • 错误消息（确切文本）
   • 配置（不含 API 密钥）
   • 重现步骤

2. 检查文档

   • API 参考
   • MCP 配置
   • 账号绑定指南

联系支持

控制台支持：

• 访问 app.browserman.run
• 前往支持 > 提交工单
• 包含详细信息

社区：

• 通过控制台查看社区论坛
• 分享解决方案并从其他用户获取帮助

常见错误代码

代码	含义	解决方案
401	未授权	检查 API 密钥
403	禁止访问	检查账号权限
404	未找到	验证账号/任务 ID
429	速率受限	等待并重试
500	服务器错误	重试或联系支持

客户端特定问题

Claude Code

问题：找不到命令

• 解决方案：安装 Claude Code：npm install -g @anthropic-ai/claude-code

问题：MCP 服务器未列出

• 解决方案：使用 claude mcp list 验证，如需要重新添加

Cursor

问题：MCP 配置未加载

• 解决方案：确保 mcp.json 在正确位置且具有有效的 JSON 语法

Claude Desktop

问题：找不到"mcp-remote"

• 解决方案：使用 npx mcp-remote 安装或改用 Claude Code

下一步

• 查看 MCP 配置指南
• 探索使用示例
• 阅读 API 文档