让你的编程代理使用你已登录的浏览器。

从哪里启动

你的 MCP 客户端通过 stdio 启动 npm 包作为本地子进程。该进程仅监听 127.0.0.1:17374。扩展拨号连接到它，然后在选定的浏览器标签页中通过 WebBrain 的代理循环执行每个任务。

服务器不是第二个浏览器，也不复制 Cookie。它是 MCP 客户端和扩展之间的本地交接点。浏览器配置文件——因此已认证会话——始终不移动。

连接前的准备

向你的 MCP 客户端注册服务器

使用以下客户端特定配置之一，仅需一次。这些是安装命令，不是你请求浏览器任务的方式。注册后，客户端会为你启动服务器，你继续正常聊天；不要在同端口上同时运行手动副本。

Codex 应用、CLI 或 IDE 扩展

codex mcp add webbrain -- npx -y @webbrain/mcp-server

Codex 将 MCP 服务器存储在 ~/.codex/config.toml 中；同一 Codex 主机上的应用、CLI 和 IDE 扩展共享该配置。对于长时间的浏览器任务，打开该文件并为工具提供超过 Codex 默认单次调用预算的时间：

[mcp_servers.webbrain]
command = "npx"
args = ["-y", "@webbrain/mcp-server"]
tool_timeout_sec = 360

更改文件后重启应用或 IDE 扩展。在 CLI 中，运行 codex mcp list 确认条目，并在 Codex 会话中使用 /mcp 检查已连接的服务器。参阅 官方 Codex MCP 指南 了解共享主机配置和所有支持选项。

Claude Code

claude mcp add --transport stdio webbrain -- npx -y @webbrain/mcp-server

显式传输匹配当前的 Claude Code MCP 配置。添加后运行 claude mcp list 检查服务器健康状况。

Cursor

在 Cursor 的 MCP 设置中添加本地 stdio 服务器，或将此内容放入 Cursor 使用的 MCP JSON 文件。格式遵循 Cursor 本地 MCP 服务器格式：

{
  "mcpServers": {
    "webbrain": {
      "command": "npx",
      "args": ["-y", "@webbrain/mcp-server"]
    }
  }
}

OpenCode

将此条目添加到 ~/.config/opencode/opencode.json，使用 OpenCode 的 本地 MCP 服务器格式：

{
  "mcp": {
    "webbrain": {
      "type": "local",
      "command": ["npx", "-y", "@webbrain/mcp-server"]
    }
  }
}

OpenClaw

在 OpenClaw 中将 WebBrain 注册为出站 MCP 服务器。不要使用 openclaw mcp serve 进行此集成：该命令使 OpenClaw 本身充当服务器，方向相反。

openclaw mcp add webbrain \
  --command npx \
  --arg -y \
  --arg @webbrain/mcp-server \
  --timeout 360

mcp add 会在保存前探测 stdio 服务器。运行 openclaw mcp status --verbose 检查已保存的定义。普通的 coding 和 messaging 工具配置文件包含已配置的 MCP 服务器；minimal 配置文件、显式 bundle-mcp 拒绝或沙箱工具策略可能会隐藏它们。参阅 OpenClaw MCP 指南 了解当前注册表和策略详情。

手动运行

手动启动对于诊断监听器很有用，但在正常使用 MCP 时不需要：

npx -y @webbrain/mcp-server

保持该终端打开。关闭它会关闭桥接监听器。从源码检出时，在 mcp-server/ 内运行 npm install、npm run build，然后 npm start。

将 WebBrain 指向本地监听器

1. 启动或重启你的 MCP 客户端。其 WebBrain 服务器必须在扩展连接之前运行。
2. 打开 WebBrain 设置。进入通用 → 高级 → 云桥接。
3. 设置精确的 URL。输入 ws://127.0.0.1:17374/extension。
4. 启用云桥接。状态应从"正在连接"变为"已连接"。名称是历史原因：此目标是本地的。
5. 验证端到端连接。要求 MCP 客户端调用 webbrain_connection。"Connected" 证明客户端、本地服务器、WebSocket 监听器和扩展握手均已就绪。

用自然语言描述浏览器任务

在 Codex、Claude Code、Cursor、OpenClaw 或 OpenCode 中，像给同事布置任务一样写出请求。提及 WebBrain 使你的意图明确无误；包括页面、期望结果、范围，以及是否允许更改。

不改变页面的读取

使用 WebBrain 读取我浏览器中已打开的 Stripe 仪表盘。列出过去七天的失败支付，包含客户、金额、货币、日期和失败原因。不要更改任何内容。

返回可预测的 JSON

使用 WebBrain 从我浏览器中已打开的仪表盘提取所有逾期发票。返回包含客户、金额、货币、到期日和发票 URL 的 JSON。不要更改任何内容。

与页面交互

使用 WebBrain 的 Act 模式打开我浏览器中已显示的客户记录，将公司名称更新为 Acme Europe。在任何最终提交或确认之前停止。

编程代理会选择 webbrain_run 进行一般读取或交互，当请求结构化数据时选择 webbrain_extract。它提供参数、监控运行，并将 WebBrain 的结果呈现回对话中。Ask 模式可以读取和提取；不能点击、输入、导航或提交。Act 模式可以交互，受 WebBrain 正常的浏览器端权限约束。

webbrain_run(
  task: "read the open Stripe dashboard and list failed payments from the last 7 days with customer, amount, currency, date, and failure reason",
  mode: "ask"
)

对于需要交互的任务，明确说"使用 WebBrain 的 Act 模式"并保持浏览器可见。WebBrain 将应用其正常的按来源能力审批提示。

MCP 客户端为你使用的工具

你通常选择结果，而不是工具。你的 MCP 客户端读取这些描述，选择适当的工具，根据你的请求填充其输入，并处理后续调用。此参考用于让你理解或调试该行为。

请求结构化 JSON

正常使用时，说出要提取什么并命名所需字段："使用 WebBrain 从已打开的仪表盘提取所有逾期发票，返回包含客户、金额、货币、到期日和发票 URL 的 JSON。"一个有能力的 MCP 客户端可以将这些字段翻译成所需的 schema 并为你调用 webbrain_extract。

下面的函数形式示例展示了客户端开发者和调试等价的工具调用。在 task 中描述选择逻辑；仅在 output_schema 中描述输出形状。

webbrain_extract(
  task: "extract every overdue invoice visible in this account; preserve the displayed currency and use ISO dates where the page provides a full date",
  output_schema: {
    type: "object",
    properties: {
      invoices: {
        type: "array",
        items: {
          type: "object",
          properties: {
            customer: { type: "string" },
            amount: { type: "number" },
            currency: { type: "string" },
            due_date: { type: "string" },
            invoice_url: { type: "string" }
          },
          required: ["customer", "amount", "currency", "due_date"]
        }
      }
    },
    required: ["invoices"]
  }
)

• 使用带有显式 properties 和 required 字段的对象根。
• 请求你需要的最窄数据。Schema 不会授予浏览器会话不可见的数据访问权限。
• 该工具是只读的，但页面文本和结果仍会发送到 WebBrain 配置的 LLM 提供商。
• 如果结果对于运行的持久快照过大，状态可能报告存储结果被截断。缩小请求并重试。

理解运行生命周期

大多数 MCP 客户端会为你管理此生命周期：它们等待结果，在需要人工输入时显示 WebBrain 的澄清问题，并用你的回答继续。下面的显式调用对客户端开发者、排查问题或有意让客户端在后台启动长时间任务很有用。

前台调用默认等待。对于长时间工作，客户端可以设置 wait: false 并使用 webbrain_status 轮询。

# 工具级参考
# 启动时不等待
webbrain_run(task: "compare the invoices across all visible pages", mode: "ask", wait: false)

# 轮询返回的 ID
webbrain_status(run_id: "mcp_…")

WebBrain 运行超时会将控制权返回给 MCP 客户端，但故意不中止浏览器任务。轮询返回的 run_id。这可防止超时在任务可能已采取重要操作后静默终止它。

当 WebBrain 提问时

暂停的快照包含人类可读的问题和 clarify_id。向用户显示该问题。逐字发送他们的回答；不要推断。

webbrain_respond(
  run_id: "mcp_…",
  clarify_id: "clarify_…",
  answer: "Use the Acme EU account."
)

选择最小权限

MCP 客户端审批和 WebBrain 审批是独立的层级。你的客户端可能在调用 webbrain_run 之前询问；WebBrain 可能在某个来源上的重要操作之前询问。一个审批不会替代另一个。

你应该保持的安全边界

• 保持监听器本地化。它绑定到 127.0.0.1。不要转发端口 17374、通过容器桥接发布，或代理到网络上。
• 本地回环不是认证。扩展发送识别握手但没有共享密钥。以你本地用户身份运行的进程可能尝试冒充扩展或服务器。将本地代码和 MCP 包视为可信软件。
• 先使用 Ask。只读工作更容易验证，爆炸半径更小。
• Act 模式保持浏览器可见。你可以在侧边栏中停止运行，意外的导航或输入应被视为停止的理由。
• 记住提供商边界。MCP 桥接保持本地，但页面内容会发送到 WebBrain 中配置的模型提供商。当内容必须保留在本地设备上时，请使用本地模型。
• 不要将超时误解为回滚。中止会停止后续步骤；它无法撤销已发送的邮件、已提交的表单、购买或其他已完成的操作。

完整设计请参阅 安全模型、隐私与数据流，以及 模式、安全与隐私指南。

按症状排查

环境配置

对于 stdio 客户端，在该客户端的 MCP 配置中设置环境变量。如果你更改了端口或路径，请精确更新 WebBrain 设置中的云桥接 URL 以匹配。

使用 LM Studio？

LM Studio 使用单独的 WebBrain Web Tools 插件，而非此 MCP 包。其 fetch_url 和 research_url 工具可以在不需要浏览器扩展的情况下读取公开页面；其浏览器工具可以通过端口 17375 将目标委派到你的已登录 Chromium 会话。

此服务器故意不做的事

• 它不启动无头浏览器或创建全新的浏览器配置文件。
• 它不通过 Firefox 构建工作。
• 它不导出 Cookie、凭据或会话存储。
• 它不直接向 MCP 客户端暴露 WebBrain 大约五十个点击、输入、框架、截图、网络和 DOM 原语。
• 它不使桥接安全地暴露到远程。
• 它不排除在 WebBrain 内配置模型的需要。

如果你需要在隔离配置文件中进行确定性的低级浏览器自动化，Playwright 风格的 MCP 服务器可能更适合。当决定性需求是你已有的已登录浏览器会话加上 WebBrain 的浏览器内安全模型时，请使用 WebBrain MCP。