浏览器

浏览器使用MCP服务器

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=安装服务器&color=0098FF" alt="在VS Code中安装"> <img alt="在VS Code Insiders中安装" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=安装服务器&color=24bfa5">

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

主要特性

• ⚡ 快速且轻量级。利用Puppeteer的标签索引，而不是基于像素的输入和可访问DOM树。
• 👁️ 视觉模式支持。当结构化数据不足以处理复杂布局和视觉元素时，提供可选的视觉理解能力。
• 🤖 优化LLM。无需视觉模型，仅依赖于结构化数据操作，减少上下文令牌的使用。
• 🧩 运行时配置灵活。通过HTTP头在运行时自定义视口大小、坐标系统因子和用户代理。
• 🌐 跨平台与扩展性。支持远程和本地浏览器，以及自定义浏览器引擎的使用。

需求

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

开始使用

本地（标准IO）

首先，使用您的客户端安装浏览器MCP服务器。典型的配置如下所示：

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

<details><summary><b>在VS Code中安装</b></summary>

您也可以使用VS Code CLI安装浏览器MCP服务器：

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

安装后，浏览器MCP服务器将在VS Code中与GitHub Copilot代理一起使用。

</details> <details> <summary><b>在Cursor中安装</b></summary>

转到 Cursor设置 -> MCP -> 添加新MCP服务器。根据喜好命名，使用命令类型并输入命令 npx @agent-infra/mcp-server-browser。您还可以通过点击“编辑”来验证配置或添加命令参数。

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

</details> <details> <summary><b>在Windsurf中安装</b></summary>

遵循Windsurf MCP 文档。使用以下配置：

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

</details> <details> <summary><b>在Claude Desktop中安装</b></summary>

遵循MCP安装 指南，使用以下配置：

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

</details>

远程（SSE / 可流式传输HTTP）

同时，使用 --port $your_port 参数启动浏览器MCP可以转换为SSE和可流式传输HTTP服务器。

# 正常运行远程MCP服务器
npx @agent-infra/mcp-server-browser --port 8089

# 使用DISPLAY环境变量运行VNC或其他虚拟显示
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端点：

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

url 设置为可流式传输HTTP：

{
  "mcpServers": {
    "browser": {
      "type": "streamable-http", // 如果有MCP客户端支持
      "url": "http://127.0.0.1::8089/mcp"
    }
  }
}

内存调用

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

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

// 类型：模块项目使用
import { createServer } from '@agent-infra/mcp-server-browser';
// 共享库项目使用
// const { createServer } = await import('@agent-infra/mcp-server-browser')

const client = new Client(
  {
    name: '测试浏览器客户端',
    version: '1.0',
  },
  {
    capabilities: {},
  },
);

const server = createServer();
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();

await Promise.all([
  client.connect(clientTransport),
  server.connect(serverTransport),
]);

// 列出工具
const result = await client.listTools();
console.log(result);

// 调用工具
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              输出版本号
  --browser <browser>        使用的浏览器或Chrome通道，可能的值：chrome, edge, firefox。
  --cdp-endpoint <endpoint>  连接的CDP端点，例如 "http://127.0.0.1:9222/json/version"
  --ws-endpoint <endpoint>   连接的WebSocket端点，例如 "ws://127.0.0.1:9222/devtools/browser/{id}"
  --executable-path <path>   浏览器可执行文件的路径。
  --headless                 在无头模式下运行浏览器，默认是有头模式
  --host <host>              绑定服务器的主机。默认是localhost。使用0.0.0.0绑定所有接口。
  --port <port>              监听SSE和HTTP传输的端口。
  --proxy-bypass <bypass>    要绕过代理的逗号分隔域名，例如 ".com,chromium.org,.domain.com"
  --proxy-server <proxy>     指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
  --user-agent <ua string>   指定用户代理字符串
  --user-data-dir <path>     用户数据目录的路径。
  --viewport-size <size>     指定浏览器视口大小（以像素为单位），例如 "1280, 720"
  --output-dir <path>        输出文件的目录路径
  --vision                   启动使用截图的服务器（默认使用Aria快照）
  -h, --help                 显示命令帮助

运行时配置

浏览器运行时需要配置 视口大小、视觉模型坐标因子 和 用户代理。这些可以通过相应的HTTP头传递：

头部	描述
x-viewport-size	浏览器视口大小，格式：宽度,高度 用逗号分隔
x-vision-factors	视觉模型坐标系因子，格式：x因子,y因子 用逗号分隔
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由update-readme.js生成 -->

API

工具

工具名称	描述	参数
browser_click	点击页面上的元素，在使用此工具之前，请使用 browser_get_clickable_elements 获取元素的索引，但不要多次调用 browser_get_clickable_elements	index (数字，可选)：要点击的元素索引
browser_close	当任务完成且不再需要浏览器时关闭浏览器
browser_close_tab	关闭当前标签页
browser_evaluate	在浏览器控制台中执行JavaScript	script (字符串，必需)：要执行的JavaScript代码，例如 () => { /* 代码 */ }
browser_form_input_fill	填充输入字段，在使用此工具之前，必须提供 'index' 或 'selector' 中的一个	selector (字符串，可选)：输入字段的CSS选择器，优先使用索引，如果未提供索引，则使用选择器<br/>index (数字，可选)：要填充的元素索引<br/>value (字符串，必需)：要填充的值<br/>clear (布尔值，可选)：是否在填充前清除现有文本
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' 中的一个	index (数字，可选)：要悬停的元素索引<br/>selector (字符串，可选)：要悬停的元素的CSS选择器
browser_navigate	导航到一个URL	url (字符串，必需)：
browser_new_tab	打开一个新的标签页	url (字符串，必需)：要在新标签页中打开的URL
browser_press_key	按键盘上的键	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, ShiftRight, ControlLeft, ControlRight, AltLeft, AltRight, MetaLeft, MetaRight, CapsLock, PrintScreen, ScrollLock, Pause, ContextMenu
browser_read_links	获取当前页面上的所有链接
browser_screenshot	截取当前页面或特定元素的屏幕截图	name (字符串，可选)：屏幕截图的名称<br/>selector (字符串，可选)：要截屏的元素的CSS选择器<br/>index (数字，可选)：要截屏的元素索引<br/>width (数字，可选)：宽度（以像素为单位，默认为视口宽度）<br/>height (数字，可选)：高度（以像素为单位，默认为视口高度）<br/>fullPage (布尔值，可选)：全屏截图（默认为false）<br/>highlight (布尔值，可选)：突出显示元素
browser_scroll	滚动页面	amount (数字，可选)：滚动的像素数（正数向下，负数向上），如果未提供数量，则滚动到底部
browser_select	使用索引选择页面上的元素，必须提供 'index' 或 'selector' 中的一个	index (数字，可选)：要选择的元素索引<br/>selector (字符串，可选)：要选择的元素的CSS选择器<br/>value (字符串，必需)：要选择的值
browser_switch_tab	切换到特定的标签页	index (数字，必需)：要切换到的标签页索引
browser_tab_list	获取标签页列表
browser_vision_screen_capture	为视觉模式截取当前页面的屏幕截图
browser_vision_screen_click	使用视觉和快照在页面上点击左键，在调用此工具之前，应先调用 browser_vision_screen_capture 一次，如果失败则回退到 browser_click	factors (数组，可选)：视觉模型坐标系缩放因子 [宽度因子, 高度因子] 用于坐标空间归一化。变换公式：x = (x_model * 屏幕宽度 * 宽度因子) / 宽度因子 y = (y_model * 屏幕高度 * 高度因子) / 高度因子 其中 x_model, y_model 是归一化的模型输出坐标（0-1），屏幕宽度/高度是屏幕尺寸，宽度因子/高度因子是量化因子，如果未知因子，请留空。大多数模型不需要此参数。<br/>x (数字，必需)：X像素坐标<br/>y (数字，必需)：Y像素坐标

资源

资源名称	URI模式	描述	MIME类型
浏览器控制台日志	console://logs		text/plain
浏览器下载	download://{name}