# @agent-infra/mcp-server-browser 中文文档 规范地址：https://npmcn.com/package/%40agent-infra/mcp-server-browser/ 版本：1\.2\.29 npm 元数据更新时间：2026-05-14T05:36:16.085Z 中文译文更新时间：2026-11-06T16:50:58.697Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40agent-infra/mcp-server-browser 原文对照：https://npmcn.com/package/%40agent-infra/mcp-server-browser/?lang=original 项目主页：https://github.com/bytedance/UI-TARS-desktop 源码仓库：https://github.com/bytedance/UI-TARS-desktop ## 关键信息（来自 npm 元数据） - 包体积（解压后）：12.4 MB，33 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：6 个 - 首次发布：2025-04-01T02:31:31.949Z - 最新版本发布：2025-12-15T06:31:26.364Z - 近 30 天下载量：2698（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：80（近 12 个月 6 个） ## 中文简介 用于浏览器的 MCP 服务器 ## 安装 ```sh npm install @agent-infra/mcp-server-browser ``` 也可以使用：`pnpm add @agent-infra/mcp-server-browser`、`yarn add @agent-infra/mcp-server-browser`、`bun add @agent-infra/mcp-server-browser` ## README ## 浏览器使用 MCP 服务器 [![NPM Downloads](https://img.shields.io/npm/d18m/@agent-infra/mcp-server-browser)](https://www.npmjs.com/package/@agent-infra/mcp-server-browser) [![smithery badge](https://smithery.ai/badge/@bytedance/mcp-server-browser)](https://smithery.ai/server/@bytedance/mcp-server-browser) [![codecov](https://codecov.io/gh/bytedance/UI-TARS-desktop/main/graph/badge.svg?component=mcp_server_browser)](https://app.codecov.io/gh/bytedance/UI-TARS-desktop/components/mcp_server_browser) [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=browser-use&config=eyJjb21tYW5kIjoibnB4IEBhZ2VudC1pbmZyYS9tY3Atc2VydmVyLWJyb3dzZXJAbGF0ZXN0In0%3D) [![Install in VS Code](https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF)](https://insiders.vscode.dev/redirect?url=vscode%253Amcp%252Finstall%253F%257B%2522name%2522%253A%2522browser%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540agent-infra%252Fmcp-server-browser%2540latest%2522%255D%257D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5)](https://insiders.vscode.dev/redirect?url=vscode-insiders%253Amcp%252Finstall%253F%257B%2522name%2522%253A%2522browser%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540agent-infra%252Fmcp-server-browser%2540latest%2522%255D%257D) 一个快速,轻量级的模型上下文协议(MCP)服务器,通过Puppeteer的结构化可访问性数据赋予LLMs以浏览器自动化的能力,其特点是可选的视觉模式,用于复杂的视觉理解和灵活的跨平台配置. ![](https://github.com/user-attachments/assets/4c401c0f-01bb-447f-89a3-7e4fdde7d58d) ### 关键特性 - **快速和轻量级**. 使用 Puppeteer 的标签索引,而不是基于像素的输入和访问 DOM 树. - **++ 愿景模式支持**. 在结构化数据不足时,可选择的视觉理解能力用于复杂的布局和视觉元素. - **\* LLM优化**. 不需要视觉模型,完全依靠结构化数据运作,减少上下文符号的使用. - **XQ 灵活运行时配置**。自定义视图大小、协调系统因子,以及运行时通过HTTP头的用户代理. - **++ 跨平面并可扩展**。支持远程和本地浏览器,使用自定义浏览器引擎. ### 所需资源 - 节点.js 18或更新 - VS 代码、 光标、 Windsurf、 Claude 桌面或任何其他 MCP 客户端 ### 开始 #### 当地( Stdio) 首先,用客户端安装浏览器MCP服务器. 一个典型的配置是这样的: ```js { "mcpServers": { "browser": { "command": "npx", "args": [ "@agent-infra/mcp-server-browser@latest" ] } } } ``` **在 VS 代码中安装** 您也可以使用 VS 代码 CLI 安装浏览器 MCP 服务器 : ```bash # For VS Code code --add-mcp '{"name":"browser","command":"npx","args":["@agent-infra/mcp-server-browser@latest"]}' ``` 安装后, 浏览器 MCP 服务器将可用 VS 代码中的您的 GitHub 副驾驶代理 . **在光标中安装** 转到 `Cursor Settings` - > (中文) `MCP` - > (中文) `Add new MCP Server`。您喜欢的名称,使用 `command` 带有命令的类型 `npx @agent-infra/mcp-server-browser`。也可以通过点击来校验配置或添加类似参数的命令 `Edit`。 。 。 . ```js { "mcpServers": { "browser": { "command": "npx", "args": [ "@agent-infra/mcp-server-browser@latest" ] } } } ``` **在 Windsurf 安装** 跟随Windsuff MCP [文档](https://docs.windsurf.com/windsurf/cascade/mcp)。使用以下配置: ```js { "mcpServers": { "browser": { "command": "npx", "args": [ "@agent-infra/mcp-server-browser@latest" ] } } } ``` **在 Claude 桌面中安装** 跟随 MCP 安装 [指南](https://modelcontextprotocol.io/quickstart/user),使用以下配置: ```js { "mcpServers": { "browser": { "command": "npx", "args": [ "@agent-infra/mcp-server-browser@latest" ] } } } ``` #### 远程( SSE / 可流 HTTP) 同时使用 `--port $your_port` 启动浏览器mcp的参数可以被转换为SSE和可流式HTTP服务器. ```bash # normal run remote mcp server npx @agent-infra/mcp-server-browser --port 8089 # run with DISPLAY environment for VNC or other virtual display DISPLAY=:0 npx @agent-infra/mcp-server-browser --port 8089 ``` 您可以使用两个 MCP 服务器远程端点中的一个 : - 可流取的 HTTP( 建议): `http://127.0.0.1::8089/mcp` - SSE : (英语) `http://127.0.0.1::8089/sse` 然后在MCP客户端配置中设置 `url` 至SSE 端点 : ```js { "mcpServers": { "browser": { "url": "http://127.0.0.1::8089/sse" } } } ``` `url` 转到可流式 HTTP : ```js { "mcpServers": { "browser": { "type": "streamable-http", // If there is MCP Client support "url": "http://127.0.0.1::8089/mcp" } } } ``` #### 纪念电话 如果您的MCP客户端是基于JavaScript / TypeScript开发的,可以直接使用进程内调用来避免要求您的用户安装命令行界面来使用浏览器MCP. ```js import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'; // type: module project usage import { createServer } from '@agent-infra/mcp-server-browser'; // commonjs project usage // const { createServer } = await import('@agent-infra/mcp-server-browser') const client = new Client( { name: 'test browser client', version: '1.0', }, { capabilities: {}, }, ); const server = createServer(); const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); await Promise.all([ client.connect(clientTransport), server.connect(serverTransport), ]); // list tools const result = await client.listTools(); console.log(result); // call tool const toolResult = await client.callTool({ name: 'browser_navigate', arguments: { url: 'https://www.google.com', }, }); console.log(toolResult); ``` ### 配置 浏览器 MCP 服务器支持以下参数 。 可在上面的JSON配置中提供,作为 `"args"` 列表 : ``` > npx @agent-infra/mcp-server-browser@latest -h -V, --version output the version number --browser browser or chrome channel to use, possible values: chrome, edge, firefox. --cdp-endpoint CDP endpoint to connect to, for example "http://127.0.0.1:9222/json/version" --ws-endpoint WebSocket endpoint to connect to, for example "ws://127.0.0.1:9222/devtools/browser/{id}" --executable-path path to the browser executable. --headless run browser in headless mode, headed by default --host host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces. --port port to listen on for SSE and HTTP transport. --proxy-bypass comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com" --proxy-server specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080" --user-agent specify user agent string --user-data-dir path to the user data directory. --viewport-size specify browser viewport size in pixels, for example "1280, 720" --output-dir path to the directory for output files --vision Run server that uses screenshots (Aria snapshots are used by default) -h, --help display help for command ``` #### 运行时配置 浏览器运行时间需要配置 `Viewport Size`, (中文(简体) ), `Vision Model Coordinate Factors`,以及 `User Agent`。这些可以通过相应的 HTTP 头来传递 : | 页眉 | 说明 | | --- | --- | | `x-viewport-size` | 浏览器视图大小, 格式 : `width,height` 用逗号分隔 | | `x-vision-factors` | 远景模型坐标系统因子,格式: `x_factor,y_factor` 用逗号分隔 | | `x-user-agent` | 用户代理字符串, 如果未指定, 默认为系统用户代理 | > **说明:** 标题为不区分大小写. 示例 ```http x-viewport-size: 1920,1080 x-vision-factors: 1.0,1.0 x-user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ``` ### 夹克 我们统一部署 VNC 和 MCP 在单一的 URL 端点下, Dockerfile 和 DockerHub 图像将一起发布! [视频](https://github.com/user-attachments/assets/e04e60aa-c9f9-4732-ac33-66e41d68056b) ### API 密码 #### 工具 | 工具名称 | 说明 | 参数 | | --- | --- | --- | | `browser_click` | 在使用工具前单击页面上的元素 `browser_get_clickable_elements` 以获取元素索引,但不调用 `browser_get_clickable_elements` 多次数 | **指数** (数目,可选): 要点击的元素索引 | | `browser_close` | 任务完成后关闭浏览器, 不再需要浏览器 | | | `browser_close_tab` | 关闭当前标签 | | | `browser_evaluate` | 在浏览器控制台执行 JavaScript | **脚本** (字符串, 需要): JavaScript 代码执行, () {} / \* 代码 \*/} | | `browser_form_input_fill` | 在使用工具前填入输入字段, 必须提供“ 索引” 或“ 选择器 ” | **选择器** (字符串,可选):用于输入字段的 CSS 选择器,优先使用索引,如果不提供索引,则使用选择器 **指数** (数目,可选): 填充要素索引 **价值** (字符串,要求): 要填充的值 **清除** (布尔,可选): 在填充前是否清除已存在的文本 | | `browser_get_clickable_elements` | 在当前页面上获取可点击或可徘徊或可选择的元素,不要多次调用此工具 | | | `browser_get_download_list` | 获取已下载文件列表 | | | `browser_get_markdown` | 获取当前页面的下标内容 | | | `browser_get_text` | 获取当前页面的文本内容 | | | `browser_go_back` | 回到上一页 | | | `browser_go_forward` | 转到下一页 | | | `browser_hover` | 隐藏页面中的元素, 必须提供“ 索引” 或“ 选择器 ” | **指数** (数目,可选): 悬浮元素索引 **选择器** (字符串,可选):用于元素徘徊的 CSS 选择器 | | `browser_navigate` | 导航到 URL | **url 密码** (字符串,要求): | | `browser_new_tab` | 打开新标签 | **url 密码** (字符串, 需要): 要打开新标签的 URL | | `browser_press_key` | 按键盘上的键 | **键** (字符串,要求): 要按键或生成的字符名称, 如 Enter, Tab, Escape, Backspace, 删除, 插入, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, ArrowLeft, ArrowRight, ArrowUp, ArrowDown, PageUp, PageDown, Home, End, ShiftLeft, ShiftRight, ControlLeft, ControlRight, AltLeft, AltRight, MetaLeft, MetaRight, CapsLock, PrintScreen, ScrollLock, Pause, CaseMenu | | `browser_read_links` | 获取当前页面上的所有链接 | | | `browser_screenshot` | 取当前页面的截图或特定元素 | **名称** (弦,可选): 截图名称 **选择器** (字符串,可选):用于元素截取的 CSS 选择器 **指数** (数字,可选):用于截图的元素索引 **宽度** (数目,可选): 在像素中的宽度( 默认: 视图宽度) **高度** (数目,可选): 在像素中的高度( 默认: 视图高度) **全页** (布尔,可选): 全页截图( 默认: 假) **突出显示** (布尔,可选): 突出显示元素 | | `browser_scroll` | 滚动页面 | **金额** (数目,可选): 要滚动的像素( 正向下, 负向上), 如果不提供数量, 滚动到页面底端 | | `browser_select` | 在页面上选择一个带有索引的元素, 必须提供“ 索引” 或“ 选择器 ” | **指数** (数目,可选): 要选择的元素索引 **选择器** (字符串,可选):用于选择元素的 CSS 选择器 **价值** (字符串,要求): 要选择的值 | | `browser_switch_tab` | 切换到特定标签 | **指数** (数量,需要):要切换到的标签索引 | | `browser_tab_list` | 获取标签列表 | | | `browser_vision_screen_capture` | 查看当前页面的视图模式 | | | `browser_vision_screen_click` | 点击页面上带有视觉和快照的鼠标左键,在调用此工具前,您应该调用 `browser_vision_screen_capture` 仅一次,倒向 `browser_click` 如果失败 | **因素** (阵列,可选):用于协调空间正常化的远景模型坐标系统缩放因子\[width factor,high factor\]. 变换公式: x = (x model \* 屏幕 width \* 宽度 factor) / 宽度 factory y = (y model \* 屏幕 高度 factor) / 高度 factor 其中x model,y model是常态化的模型输出坐标(0-1),screen width/高度是屏幕维度,宽度 因素/高度 factor是量化因子,如果因子未知,请留入空. 大多数模型不需要这个参数. **页:1** (数量,需要): X 像素坐标 **尔** (数目,需要):Y像素坐标 | #### 资源 | 资源名称 | URI 模式 | 说明 | MIME 类型 | | --- | --- | --- | --- | | 浏览器控制台日志 | `console://logs` | | 文本/说明 | | 浏览器下载 | `download://{name}` | | 基于文件扩展名的自动标识 | | 浏览器屏幕截图 | `screenshot://{name}` | | 基于文件扩展名的自动标识 | ### 发展 查阅 http://127.0.0.1:6274/: ```bash npm run dev ``` ### 扩展 CLI 条目 ```js #!/usr/bin/env node const { BaseLogger, setConfig, addMiddleware, } = require('@agent-infra/mcp-server-browser/request-context'); class CustomLogger extends BaseLogger { info(...args) { console.log('custom'); console.log(...args); } } addMiddleware((req, res, next) => { console.log('req', req.headers); next(); }); setConfig({ logger: new CustomLogger(), }); // start server require('@agent-infra/mcp-server-browser/index'); ``` ## 常见问题 ### @agent-infra/mcp-server-browser 是什么？ 用于浏览器的 MCP 服务器 ### 如何安装 @agent-infra/mcp-server-browser？ 在项目目录运行 npm install @agent-infra/mcp-server-browser，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-server-browser，可以用 npx mcp-server-browser 直接运行。 ### @agent-infra/mcp-server-browser 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @agent-infra/mcp-server-browser 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @agent-infra/mcp-server-browser 可以商用吗？ @agent-infra/mcp-server-browser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @agent-infra/mcp-server-browser 的下载量有多少？ 根据 npm 官方下载统计，@agent-infra/mcp-server-browser 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,698 次，日均约 90 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @agent-infra/mcp-server-browser 还在维护吗？ 最新版本 1\.2\.29 发布于 2025/12/15（10 个月前）；至今共发布 80 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/04/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。