AI导哈

浏览器自动化MCP服务器

一个快速、轻量级的模型上下文协议（MCP）服务器，通过Puppeteer的结构化可访问性数据为LLM提供浏览器自动化功能，支持可选视觉模式以实现复杂的视觉理解，并具有灵活的跨平台配置。

  • by bytedance
  • TypeScript
  • 混合部署
  • 3.9万 星标
  • 更新于
在 GitHub 查看 bytedance/UI-TARS-desktop

使用说明

浏览器使用MCP服务器

一个快速、轻量级的模型上下文协议（MCP）服务器，它通过Puppeteer的结构化无障碍数据，为大型语言模型（LLMs）提供浏览器自动化能力，具备可选的视觉模式以实现复杂视觉理解，并支持灵活、跨平台的配置。

主要特点

  • ⚡ 快速且轻量使用Puppeteer的标签索引，而非基于像素的输入和无障碍性DOM树。
  • 👁️ 视觉模式支持当结构化数据不足时，可选的复杂布局和视觉元素的视觉理解能力。
  • **🤖 优化后的大型语言模型（LLM）**无需视觉模型，仅基于结构化数据运行，减少上下文令牌的使用，上下文需求较低。
  • 🧩 灵活的运行时配置在运行时通过HTTP头自定义视口大小、坐标系因子和用户代理。
  • 🌐 跨平台且可扩展支持远程和本地浏览器，使用自定义浏览器引擎。

要求

  • Node.js 18 或更高版本
  • VS Code、Cursor、Windsurf、Claude Desktop 或任何其他MCP客户端

开始入门

本地（工作室）

首先，将浏览器MCP服务器与您的客户端进行安装。一个典型的配置如下：

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}
Install in VS Code

您也可以使用 VS Code 命令行界面 (CLI) 安装 Browser MCP 服务器：

# For VS Code
code --add-mcp '{"name":"browser","command":"npx","args":["@agent-infra/mcp-server-browser@latest"]}'

安装完成后，您可以在VS Code中使用您的GitHub Copilot代理来访问浏览器MCP服务器。

Install in Cursor

首选 Cursor Settings -> MCP -> Add new MCP Server按照您的喜好命名，使用 command 使用命令输入类型 npx @agent-infra/mcp-server-browser您也可以通过点击来验证配置或添加类似命令的参数 Edit。

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}
Install in Windsurf

关注Windsuff MCP 文件、文档使用以下配置：

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}
Install in Claude Desktop

按照MCP安装程序进行安装 指南；向导使用以下配置：

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": [
        "@agent-infra/mcp-server-browser@latest"
      ]
    }
  }
}

远程（SSE / 可流式HTTP）

同时，使用 --port $your_port 参数用于启动浏览器，MCP（可能指某种中间件或服务器组件）可以转换为SSE（服务器发送事件）和可流式传输的HTTP服务器。

# 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
  • 上海证券交易所 http://127.0.0.1::8089/sse

然后在MCP客户端配置中，设置 url 到SSE终端点：

{
  "mcpServers": {
    "browser": {
      "url": "http://127.0.0.1::8089/sse"
    }
  }
}

url 到Streamable HTTP：

{
  "mcpServers": {
    "browser": {
      "type": "streamable-http", // If there is MCP Client support
      "url": "http://127.0.0.1::8089/mcp"
    }
  }
}

内存中调用

如果您的MCP客户端是基于JavaScript/TypeScript开发的，您可以直接使用进程内调用来避免用户需要安装命令行界面以使用Browser MCP。

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>        browser or chrome channel to use, possible values: chrome, edge, firefox.
  --cdp-endpoint <endpoint>  CDP endpoint to connect to, for example "http://127.0.0.1:9222/json/version"
  --ws-endpoint <endpoint>   WebSocket endpoint to connect to, for example "ws://127.0.0.1:9222/devtools/browser/{id}"
  --executable-path <path>   path to the browser executable.
  --headless                 run browser in headless mode, headed by default
  --host <host>              host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
  --port <port>              port to listen on for SSE and HTTP transport.
  --proxy-bypass <bypass>    comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"
  --proxy-server <proxy>     specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"
  --user-agent <ua string>   specify user agent string
  --user-data-dir <path>     path to the user data directory.
  --viewport-size <size>     specify browser viewport size in pixels, for example "1280, 720"
  --output-dir <path>        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 用户代理字符串，若未指定则默认使用系统用户代理

注： 头部名称不区分大小写。

示例：

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

Docker

我们已将VNC和MCP的部署统一到一个单一的URL端点下，Dockerfile和DockerHub镜像将一同发布！ 视频

API

工具

工具名称 描述 参数
browser_click 在使用工具之前，点击页面上的一个元素 browser_get_clickable_elements 获取元素的索引，但不调用 browser_get_clickable_elements 多次 索引 （数字，可选）：要点击的元素的索引
browser_close 任务完成后，若浏览器不再需要，请关闭浏览器
browser_close_tab 关闭当前标签页
browser_evaluate 在浏览器控制台中执行JavaScript 脚本 （字符串，必需）：要执行的JavaScript代码，() => { /* 代码 */ }
browser_form_input_fill 在使用工具之前，请填写输入框，必须提供“index”或“selector”中的一个 选择器 （字符串，可选）：输入字段的CSS选择器，优先使用索引，如果未提供索引，则使用选择器
索引 （数字，可选）：要填充的元素的索引
价值 (字符串，必需): 要填充的值
清晰；清楚 （布尔值，可选）：在填充前是否清除现有文本
browser_get_clickable_elements 获取当前页面上可点击、悬停或选择的元素，不要多次调用此工具
browser_get_download_list 获取已下载文件的列表
browser_get_markdown 获取当前页面的Markdown内容
browser_get_text 获取当前页面的文本内容
browser_go_back 返回上一页
browser_go_forward 转到下一页
browser_hover 将鼠标悬停在页面上的某个元素上，必须提供“index”或“selector” 索引 （数字，可选）：要悬停的元素的索引
选择器 （字符串，可选）：用于悬停的元素的CSS选择器
browser_navigate 导航到URL 网址 (字符串，必填)：
browser_new_tab 打开一个新标签页 网址 （字符串，必填）：要在新标签页中打开的URL
browser_press_key 按下键盘上的一个键 关键 (字符串，必填)：要按下的键名或要生成的字符，例如 Enter（回车）、Tab（制表）、Escape（退出）、Backspace（退格）、Delete（删除）、Insert（插入）、F1、F2、F3、F4、F5、F6、F7、F8、F9、F10、F11、F12、ArrowLeft（左箭头）、ArrowRight（右箭头）、ArrowUp（上箭头）、ArrowDown（下箭头）、PageUp（翻页上）、PageDown（翻页下）、Home（首页）、End（末尾）、ShiftLeft（左Shift）、ShiftRight（右Shift）、ControlLeft（左Ctrl）、ControlRight（右Ctrl）、AltLeft（左Alt）、AltRight（右Alt）、MetaLeft（左Meta）、MetaRight（右Meta）、CapsLock（大写锁定）、PrintScreen（打印屏幕）、ScrollLock（滚动锁定）、Pause（暂停）、ContextMenu（上下文菜单）
browser_read_links 获取当前页面上的所有链接
browser_screenshot 对当前页面或特定元素进行截图 名字 （字符串，可选）：截图的名称
选择器 (字符串，可选)：用于截图元素的CSS选择器
索引 （数字，可选）：要截图的元素的索引
宽度 （数字，可选）：以像素为单位的宽度（默认：视口宽度）
高度 （数字，可选）：高度（以像素为单位）（默认：视口高度）
fullPage（在中文中，这个短语通常不直接翻译，而是根据上下文理解为“全屏”或“全页面”的意思，但在这里为了保持原文的格式，我们直接保留“fullPage”） (布尔值，可选)：是否截取全页面截图（默认：false）
突出；强调 (布尔值，可选)：突出显示该元素
browser_scroll 滚动页面 金额；数量 （数字，可选）：要滚动的像素数（正数表示向下，负数表示向上），如果未提供数量，则滚动到页面底部
browser_select 选择页面上的一个元素，使用索引，必须提供“index”或“selector” 索引 （数字，可选）：要选择的元素的索引
选择器 （字符串，可选）：用于选择元素的CSS选择器
价值 (字符串，必填): 要选择的值
browser_switch_tab 切换到特定标签页 索引 （数字，必填）：用于切换的制表符索引
browser_tab_list 获取标签页列表
browser_vision_screen_capture 为视觉模式截取当前页面的截图
browser_vision_screen_click 在包含视觉和快照的页面上点击鼠标左键，在调用此工具之前，您应该先调用 browser_vision_screen_capture 首先仅尝试一次，若失败则回退到 browser_click 如果失败 因素 （数组，可选）：视觉模型坐标系的缩放因子[宽度因子，高度因子]，用于坐标空间归一化。转换公式：x = (x_model * 屏幕宽度 * 宽度因子) / 宽度因子；y = (y_model * 屏幕高度 * 高度因子) / 高度因子，其中x_model、y_model为归一化后的模型输出坐标（0-1），屏幕宽度/高度为屏幕尺寸，宽度因子/高度因子为量化因子。如果因子未知，则留空。大多数模型不需要此参数。
x （数字，必填）：X像素坐标
y (数字，必填)：Y 像素坐标

资源

资源名称 URI 模式 描述 MIME 类型
（无对应中文） （无对应中文） （无对应中文） （无对应中文）
text/plain（纯文本） download://{name} 浏览器下载
基于文件扩展名的自动识别 screenshot://{name} 浏览器截图

| | 基于文件扩展名的自动识别 |

发展

npm run dev

访问 http://127.0.0.1:6274/

#!/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');

相关 MCP