AI浏览器 MCP Server

概述

AI浏览器 MCP Server 在本地启动后监听 127.0.0.1:9222，对外暴露标准 MCP 协议接口。AI 客户端通过 tools/call 调用 browser_navigate、browser_screenshot 等工具，即可操控内嵌 CEF 浏览器完成自动化任务。

客户使用手册

面向终端客户：无需了解 MCP 协议，按手册完成安装与 Cursor 接入后，用自然语言让 AI 操控浏览器。

快速开始

加载中...

技能书与配置说明书

以下 Markdown 随编译复制到 exe 同目录 docs/，可通过 HTTP 直接访问：

架构说明

┌─────────────┐    stdio     ┌──────────────┐   POST /mcp   ┌──────────────────┐
│ Cursor/AI   │ ──────────► │ mcp_bridge.js│ ────────────► │ MCP_Server.wsv   │
└─────────────┘              └──────────────┘               │  (HTTP + WS)     │
┌─────────────┐    WS/HTTP                              ┌──►│                  │
│ 自定义脚本   │ ────────────────────────────────────────┘   └────────┬─────────┘
└─────────────┘                                                        │
                                                              FBrowser CEF 浏览器

• MCP_Server.wsv — JSON-RPC 分发、sync-wait、batch、HTTP 路由、工具注册表
• MCP_Server_Core / Form / VIP / System / Workflow — 模块化工具分派（Core 导航/CDP、Form 填表、VIP 高级、System 元工具、Workflow 步骤链）
• MCP_BrowserEvents.wsv — 网络/控制台/导航 Hook、事件记录
• MCP_Callbacks.wsv — JS/VIP 异步回调、任务结果存储、DOM 语义失败检测
• mcp_bridge.js — Cursor stdio 桥接，自动读取 mcp_connect.json

API 端点

curl 示例

curl -X POST http://127.0.0.1:9222/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"browser_get_url","arguments":{}}}'

MCP 协议流程

1. initialize

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-06-21","clientInfo":{"name":"my-app","version":"1.0"}}}

2. notifications/initialized

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. tools/list — 获取工具

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

4. tools/call — 调用工具

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}

直接命令（可选）

也可将 method 直接设为工具名，跳过 tools/call 包装：

{"jsonrpc":"2.0","id":4,"method":"browser_get_title","params":{"browser_id":1}}

工具名同时支持 browser.navigate 与 browser_navigate 双路由。

Cursor 接入

推荐使用 mcp_bridge.js 作为 stdio 子进程，由 Cursor 管理生命周期：

// .cursor/mcp.json
{
  "mcpServers": {
    "ai-browser": {
      "command": "node",
      "args": ["CEFbro/AI浏览器/mcp_bridge.js"],
      "env": {
        "AI_BROWSER_MCP_HTTP_POST": "http://127.0.0.1:9222/mcp",
        "AI_BROWSER_MCP_HOST": "127.0.0.1",
        "AI_BROWSER_MCP_PORT": "9222",
        "AI_BROWSER_MCP_CURSOR_MODE": "0"
      }
    }
  }
}

桥接脚本配置优先级：AI_BROWSER_MCP_HTTP_POST → mcp_connect.json → 默认 127.0.0.1:9222。桥接自动修复 Cursor 协议版本与 JSON-RPC id。

工具分类

完整工具列表请访问 /tools/list 或欢迎页工具搜索。主要分类如下：

系统 / 元工具

导航与页面

browser_navigate browser_get_url browser_get_title browser_reload browser_back browser_forward browser_list browser_status …

JS / DOM / 填表

browser_execute_js browser_evaluate browser_dom_query browser_fill_set_value browser_fill_click …

网络 / 拦截 / 调试

browser_network browser_collect browser_intercept browser_cdp_call browser_event browser_wait …

VIP 高级 VIP

browser.mouse_click/move/wheel browser.key_event browser.set_proxy 已内置VIP优先路径。VIP独有: browser_vip_mouse_press/release browser_vip_key_input/type browser_vip_fingerprint_* 指纹/扩展等。

Sync-Wait / 异步任务

v2.5 起，常用读操作默认 sync-wait：在同一次 tools/call 内轮询 async 任务并返回结果，响应可含 "_sync_waited":true。无需客户端二次 mcp_result。

默认 sync-wait 白名单：get_title、evaluate、console_eval、dom_query、dom_set_value、dom_click、get_frames、frame_names、fill_exists、fill_attr_get；get_text / dom_get_html 仅当传入 selector 时；debugger 全套（VIP）。

batch：默认对子命令自动跟随 async 结果；子命令失败时外层 success:false；batch 级 async_only:true 关闭跟随。

纯异步轮询

非白名单或显式 async_only:true 时，返回 task_id（格式 task_<毫秒>_<盐>_<计数>），通过 mcp_result 查询：

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"mcp_result","arguments":{"request_id":"task_xxx"}}}

工作流 workflow

将多步 MCP 调用编排为 JSON 步骤链，存放于 exe 同目录 workflows/（环境变量 AI_BROWSER_WORKFLOWS_DIR 可覆盖）。

加载优先级：name/file 优先读磁盘文件；内联 definition 仅作 fallback（空 definition:{} 不会拦截文件加载）。

步骤 JSON 示例

[
  { "tool": "browser_ping", "args": {} },
  { "delay_ms": 300 },
  { "tool": "browser_navigate", "args": { "url": "about:blank" } },
  { "tool": "browser_wait", "args": { "condition": "load", "timeout_ms": 5000 } }
]

每步可选 on_error："stop"（默认）或 "continue"。内置示例：hello.json、ping_navigate.json。

测试套件

一键全量

node CEFbro/AI浏览器/run_all_tests.js          # 完整 ~60–90s
node CEFbro/AI浏览器/run_all_tests.js --quick   # regression + smoke ~5s

顺序：regression_sync_wait → full_test → tool_test_all → scenario_test → workflow_runner。失败即停（--continue 可继续）。

事件监控与数据采集

browser_collect 统一入口：网络/控制台/场景预备/事件 Hook。查询导航等事件用 browser_event。

场景预备

{"name":"browser_collect","arguments":{"action":"reverse_prepare","clear":true}}
{"name":"browser_collect","arguments":{"action":"debug_prepare"}}
{"name":"browser_collect","arguments":{"action":"automation_prepare"}}

事件监控

{"name":"browser_collect","arguments":{"action":"event_all_enable"}}
{"name":"browser_event","arguments":{"event_type":"navigate"}}

支持 event_load_enable、event_resource_enable、event_dialog_enable 等单项；event_all_disable 批量关闭。详见 使用技能书 与 skills/AI浏览器MCP.md。

CDP 调试

• browser_cdp_call — 发送 CDP 命令
• browser_cdp_event — 监听 CDP 事件
• browser_vip_enable_devtools_observer — VIP DevTools 消息监听

配置文件 mcp_config.json

放在 exe 同目录，启动时自动加载。完整说明见 MCP工具配置说明书.md。

{
  "port": 9222,
  "bind_address": "127.0.0.1",
  "disable_auth": true,
  "rate_limit_per_minute": 0,
  "enable_network_log": true,
  "enable_console_log": false,
  "enable_response_cache": false,
  "network_log_max_bytes": 262144,
  "vip_code": "",
  "auto_download_save": true,
  "auto_dismiss_js_dialog": false
}

非本地绑定且未配置 api_key 时，启动日志会输出安全警告。

环境变量

exe 同目录还会生成 mcp_connect.json，包含全部连接 URL。

常见问题

连接失败 / ECONNREFUSED

确认 AI浏览器.exe 已启动。运行 node mcp_bridge.js --check 排查。

browsers: 0

主窗口浏览器尚未创建，等待数秒或打开 GUI 窗口。

工具返回 task_id 但 mcp_result 为空

若未设 async_only:true，白名单工具应已 sync-wait 直接返回。纯异步任务可能仍在执行，稍等后重试。

关闭窗口后 MCP 还在吗？

是的。关闭窗口仅隐藏到托盘，MCP 继续运行。托盘右键可真正退出。

文档/静态资源 404

请确认 exe 同目录存在 docs/ 文件夹（重新编译或安装完整发布包）。新客户请读 客户使用手册。

页面卡住 / MCP 超时

多见于 debugger 暂停未恢复。执行 node scenarios/debugger_unfreeze.js，或调用 browser_restore_gui、browser_reload。

POST 加密参数扫描失败

先 unfreeze，再 node scenarios/douyin_xhr_encrypt_scan.js --skip-navigate --wait 20 --scroll。勿并行跑多个 MCP 脚本。