使用说明

代理浏览器mcp

浏览器自动化MCP（模型上下文协议）服务器由代理浏览器.

此MCP服务器通过MCP协议提供全面的浏览器自动化功能，使AI代理能够以编程方式与网页交互。

特性

导航：导航到URL、后退/前进、重新加载页面
元素交互：单击、填充、键入、悬停、拖放、上传文件
语义定位器：按角色、文本、标签、占位符、alt文本、标题、测试ID查找元素
快照：获取带有元素引用的可访问性树，以进行确定性交互
截图：捕获整页或元素截图
表单：选中/取消选中复选框，选择下拉菜单，管理输入
JavaScript执行：在页面上下文中运行自定义JavaScript
Cookie和存储：管理Cookie、本地存储、会话存储
网络控制：拦截请求、模拟响应、跟踪网络活动
选项卡和窗口：管理多个选项卡和窗口
框架：在iframe之间切换
浏览器设置：设置视口、模拟设备、地理位置、媒体功能
调试：跟踪、控制台日志、页面错误
录制：屏幕录制和视频流
PDF导出：将页面另存为PDF

安装

npm install agent-browser-mcp

或者从源代码构建：

git clone https://github.com/xiahanhan/agent-browser-mcp.git
cd agent-browser-mcp
npm install
npm run build

设置

1.安装Chromium浏览器

npx playwright install chromium

在Linux上，您可能还需要系统依赖关系：

npx playwright install-deps chromium

2.配置MCP客户端

添加到您的MCP客户端配置中（例如，Claude Desktop配置位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

选项A：直接npx安装（推荐）

{
  "mcpServers": {
    "agent-browser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:quantmew/agent-browser-mcp"]
    }
  }
}

此方法会自动从GitHub下载并运行最新版本，无需手动安装。

选项B：本地安装

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/agent-browser-mcp/dist/index.js"]
    }
  }
}

3.环境变量（可选）

# Use a custom browser executable (e.g., for serverless)
export AGENT_BROWSER_EXECUTABLE_PATH="/path/to/chromium"

# Run in headed mode (show browser window)
export AGENT_BROWSER_HEADED="1"

用法

基本工作流程

导航到页面

browser_navigate({ url: "https://example.com" })

获取快照 （带有元素引用的可访问性树）

browser_snapshot()
// Returns:
// - heading "Example Domain" [ref=e1] [level=1]
// - link "More information..." [ref=e2]

与元素互动 使用参考文献

browser_click({ selector: "@e2" })
browser_fill({ selector: "@e3", value: "test@example.com" })

示例：登录流程

// Navigate to login page
browser_navigate({ url: "https://example.com/login" })

// Get interactive elements
browser_snapshot({ interactiveOnly: true })

// Fill login form
browser_fill({ selector: "@e1", value: "user@example.com" })
browser_fill({ selector: "@e2", value: "password" })

// Click submit button
browser_click({ selector: "@e3" })

// Wait for navigation
browser_wait_for_url({ url: "**/dashboard" })

// Take screenshot
browser_screenshot({ path: "dashboard.png" })

// Close browser
browser_close()

示例：语义定位器

// Find by ARIA role
browser_find_by_role({
  role: "button",
  name: "Submit",
  action: "click"
})

// Find by text
browser_find_by_text({
  text: "Sign In",
  action: "click"
})

// Find by label
browser_find_by_label({
  label: "Email",
  action: "fill",
  value: "test@example.com"
})

示例：表单交互

// Fill inputs
browser_fill({ selector: "#name", value: "John Doe" })
browser_select({ selector: "#country", values: "USA" })

// Check checkbox
browser_check({ selector: "#agree" })

// Upload file
browser_upload({ selector: "#file", files: "/path/to/file.pdf" })

// Submit form
browser_click({ selector: "button[type='submit']" })

示例：JavaScript执行

// Execute custom JavaScript
browser_evaluate({
  script: "document.title"
})

// With arguments
browser_evaluate({
  script: "(a, b) => a + b",
  args: [1, 2]
})

// Wait for condition
browser_wait_for_function({
  expression: "window.ready === true"
})

示例：网络控制

// Mock API response
browser_network_route({
  url: "**/api/**",
  response: {
    status: 200,
    body: '{"success": true}',
    contentType: "application/json"
  }
})

// Block requests
browser_network_route({
  url: "**/analytics/**",
  abort: true
})

// View network requests
browser_network_requests({ filter: "api" })

// Remove routes
browser_network_unroute({ url: "**/api/**" })

示例：Cookie和存储

// Get all cookies
browser_cookies_get()

// Set cookies
browser_cookies_set({
  cookies: [{
    name: "session",
    value: "abc123",
    domain: "example.com"
  }]
})

// Get localStorage
browser_storage_get({ type: "local" })

// Set localStorage
browser_storage_set({
  type: "local",
  key: "user",
  value: '{"id": 123}'
})

// Clear storage
browser_storage_clear({ type: "local" })

示例：浏览器设置

// Set viewport size
browser_set_viewport({ width: 1920, height: 1080 })

// Emulate device
browser_set_device({ device: "iPhone 14" })

// Set geolocation
browser_set_geolocation({
  latitude: 37.7749,
  longitude: -122.4194
})

// Emulate dark mode
browser_emulate_media({ colorScheme: "dark" })

// Set timezone
browser_set_timezone({ timezone: "America/New_York" })

示例：选项卡和窗口

// Open new tab
browser_tab_new({ url: "https://example.com" })

// List tabs
browser_tab_list()

// Switch to tab
browser_tab_switch({ index: 1 })

// Close current tab
browser_tab_close()

// Open new window
browser_window_new({
  viewport: { width: 800, height: 600 }
})

工具参考

元素交互

browser_click -点击元素
browser_dblclick -双击元素
browser_fill -清除并填写输入
browser_type -键入文本
browser_press -按键
browser_hover -将鼠标悬停在元素上
browser_focus -焦点元素
browser_select -选择下拉选项
browser_check -选中复选框
browser_uncheck -取消选中复选框
browser_tap -轻触元件（触摸）
browser_clear -清晰输入
browser_scroll -滚动页面/元素
browser_drag -拖放
browser_upload -上传文件

获取元素信息

browser_get_text -获取文本内容
browser_get_inner_text -获取内部文本
browser_get_inner_html -获取内部HTML
browser_get_attribute -获取属性值
browser_get_value -获取输入值
browser_is_visible -检查是否可见
browser_is_enabled -检查是否启用
browser_is_checked -检查是否已检查
browser_count -统计匹配元素
browser_bounding_box -获取边界框
browser_highlight -突出显示元素
browser_styles -获取计算样式

语义定位器

browser_find_by_role -按ARIA角色查找
browser_find_by_text -按文本查找
browser_find_by_label -按标签查找
browser_find_by_placeholder -按占位符查找
browser_find_by_alt_text -按alt文本查找
browser_find_by_title -按标题属性查找
browser_find_by_test_id -按测试ID查找
browser_find_nth -查找第N个匹配元素

等待

browser_wait -等待元素或时间
browser_wait_for_url -等待URL
browser_wait_for_load_state -等待负载状态
browser_wait_for_function -等待JS条件

JavaScript

browser_evaluate -执行JavaScript

内容

browser_get_content -获取页面HTML
browser_set_content -设置页面HTML

PDF

browser_pdf -另存为PDF

选项卡和窗口

browser_tab_list -列表选项卡
browser_tab_new -打开新选项卡
browser_tab_switch -切换到选项卡
browser_tab_close -关闭选项卡
browser_window_new -打开新窗口

框架

browser_frame -切换到iframe
browser_main_frame -切换到主机

Cookie和存储

browser_cookies_get -获取Cookie
browser_cookies_set -设置Cookie
browser_storage_get -获取存储空间
browser_storage_set -设置存储
browser_storage_clear -清空存储

浏览器设置

browser_set_viewport -设置视口大小
browser_set_device -模拟设备
browser_set_geolocation -设置地理位置
browser_set_offline -设置离线模式
browser_emulate_media -模拟媒体功能
browser_set_timezone -设置时区
browser_set_locale -设置区域设置
browser_set_headers -设置HTTP标头
browser_set_credentials -设置HTTP凭据

网络

browser_network_route -拦截请求
browser_network_unroute -删除路线
browser_network_requests -获取请求
browser_wait_for_download -等待下载
browser_download -触发器下载
browser_response_body -获取响应正文

对话框

browser_dialog_accept -接受对话框
browser_dialog_dismiss -取消对话框

调试

browser_console -获取控制台消息
browser_errors -获取页面错误
browser_trace_start -开始跟踪
browser_trace_stop -停止追踪

高级输入

browser_keyboard -键盘快捷键
browser_key_down -按住键
browser_key_up -释放钥匙
browser_mouse_move -移动鼠标
browser_mouse_down -按下鼠标按钮
browser_mouse_up -松开鼠标按钮
browser_wheel -鼠标滚轮

杂项

browser_select_all -选择所有文本
browser_set_value -设置输入值
browser_multiselect -多选下拉菜单
browser_dispatch_event -调度事件
browser_add_script -添加脚本标签
browser_add_style -添加样式标签
browser_add_init_script -添加初始化脚本
browser_bring_to_front -带到前面

录制和状态

browser_screencast_start -开始屏幕录制
browser_screencast_stop -停止屏幕录制
browser_recording_start -开始录制
browser_recording_stop -停止录制
browser_recording_restart -重新开始录制
browser_state_save -保存状态
browser_state_load -负载状态
browser_har_start -启动HAR。
browser_har_stop - 停止HAR
browser_clipboard -剪贴板操作

控制

browser_close -关闭浏览器

发展

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Type check
npm run typecheck

# Format code
npm run format

建筑

此MCP服务器包装代理浏览器图书馆，提供：

剧作家 浏览器自动化
使用可访问性树和元素引用生成快照
语义定位器（角色、文本、标签、占位符等）
会话管理
网络侦听
多标签/窗口支持

许可证

阿帕奇-2.0

学分

基于代理浏览器 Vercel实验室。