AI导哈

浏览器自动化工具

基于MCP和Selenium的浏览器自动化工具，支持多代理并行操作和HTML截断功能。

  • by janspoerer
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 janspoerer/mcp_browser_use

使用说明

MCP浏览器使用




使用此MCP可以实现什么

该项目旨在使AI代理能够使用模型上下文协议（MCP）和Selenium执行web使用、浏览器自动化、抓取和自动化。

此MCP的特殊功能是它可以处理多个代理访问多个浏览器 窗户一个人不需要启动多个Docker镜像、VM或计算机来拥有多个抓取代理。人们仍然可以使用 一个浏览器配置文件 所有代理人。每个代理都有自己的窗口，它们不会相互干扰。

这使得处理多个代理变得无缝：只需启动任意数量的代理，它就会正常工作！ 使用两个Claude Code实例、一个Codex CLI实例、一种Gemini CLI实例和一个 fast-agent 实例——所有这些都在一台计算机上，都使用相同的浏览器配置文件，并且都（在某种程度上）并行工作。

我们的使命是让人工智能代理在最少的人工监督下完成任何网络任务——所有这些都基于自然语言指令。

功能亮点

  • HTML截断： MCP允许您配置HTML页面的截断。其他抓取MCP可能会用比上下文窗口大的可访问性快照或HTML转储淹没AI。此MCP将通过设置来帮助您管理最大页面大小 MCP_MAX_SNAPSHOT_CHARS 环境变量。
  • 多浏览器窗口和多代理： 您可以将多个代理独立连接到此MCP，而不需要代表代理进行协调。每个代理都可以与 相同的 浏览器配置文件，当登录应跨代理持久化时，这很有帮助。每个代理都有自己的浏览器窗口，因此它们不会相互干扰。使用Chrome DevTools协议TargetId来识别浏览器窗口。

已知限制

  • Iframe上下文： iframe中的多步交互需要指定 iframe_selector 对于每一个动作。每次工具调用后，浏览器上下文都会重置以确保可靠性。对于iframe工作流，在每个工作流中重复iframe选择器参数 click_element, fill_text，或 debug_element 电话。

配置/安装

1.克隆并创建虚拟环境

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2.安装Chrome测试版

我们建议使用Chrome Beta版（而不是您的常规Chrome），这样AI代理就可以在远程调试的情况下运行，而不会干扰您的日常浏览。

macOS：

brew install --cask google-chrome-beta

Ubuntu/Debian：

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

窗户： 从下载并安装Chrome测试版 google.com/chrome/beta.

安装后，验证：

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Linux无头服务器-Xvfb（虚拟显示）

Chrome需要一个显示器。在无头Linux服务器（无GUI）上，使用 Xvfb:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

添加 export DISPLAY=:99 到你的 .bashrc 或 .profile 使其成为永久性的。

3.配置并启动

  • 安装Chrome Beta后，指向您的Chrome Beta可执行文件 .mcp.json 如下面的环境变量配置部分所述。
  • 启动MCP服务器（如果您不知道如何操作，请查看下面的“如何使用（此）MCP”一节）。

如何使用（此）MCP

请参考 MCP关于modelcontextprotocol.io的文档.

请注意，您需要在MCP配置文件指向的Python环境中安装所有依赖项。例如，如果您指向 python 或 python3 可执行文件，您将指向全局Python环境。通常，我们更倾向于指向一个虚拟环境，例如：

/Users/yourname/code/mcp_browser_use/.venv/bin/python

如果您已将此存储库克隆到本地 code 文件夹中，您的MCP配置文件应该如下所示：

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

它将在这里（在macOS中）： /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json.

请参考 requirements.txt 查看需要安装哪些依赖项。

重新启动Claude以查看JSON配置是否有效。如果出现问题，Claude将为您提供MCP的错误日志。

如果设置成功，您将在Claude的“新聊天”窗口的右下角看到一个小锤子图标。锤子旁边是MCP提供的功能数量。

单击锤子查看可用工具。

环境变量配置

重要： 在项目根目录中定义所有环境变量 .mcp.json 文件， 非 在 .env 文件夹。这确保了没有冲突的单一真相来源。

推荐配置（Chrome测试版）

将环境变量添加到 env 你的部分 .mcp.json 文件：

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Windows示例：

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

环境变量参考

变量 描述 示例
BETA_PROFILE_NAME 要使用的Chrome配置文件的名称 "SeleniumProfile"
BETA_EXECUTABLE_PATH Chrome Beta可执行文件的路径 请参阅上面的示例
BETA_PROFILE_USER_DATA_DIR Chrome Beta用户数据目录 见上面的示例
CHROME_REMOTE_DEBUG_PORT Chrome远程调试端口 "9225"
MCP_HEADLESS 在无头模式下运行（0=否，1=是） "0"
MCP_ENABLE_EXTENSIONS 启用Chrome扩展程序（0=否，1=是） "1"
MAX_SNAPSHOT_CHARS 最大HTML快照大小 "10000"

为什么要使用Chrome Beta？

使用Chrome Beta（或Canary）可防止与常规Chrome浏览器发生冲突：

  • AI代理要求Chrome在启用远程调试的情况下运行
  • 您的普通Chrome实例无法通过远程调试运行
  • Chrome Beta允许两者在同一系统上共存

个人资料建议

  • 使用专用配置文件 喜欢 "SeleniumProfile" （不是 "Default")
  • 这可以防止手动打开Chrome Beta时发生冲突
  • 扩展名和登录名在会话中持续存在于此配置文件中
  • 每个AI代理都有自己的浏览器窗口，但共享配置文件

可用工具

调试

通过在主浏览器（而不是自动浏览器）中访问此URL来检查浏览器是否正在运行：

http://127.0.0.1:9223/json/version

如果浏览器正在运行，它将显示如下内容：

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

锁定文件和协调

此MCP使用基于文件的锁定来协调访问同一浏览器配置文件的多个代理。所有锁文件都存储在 tmp/mcp_locks/ 在项目根目录中，便于检查。

锁定文件类型

动作锁(<hash>.softlock.json 和 <hash>.softlock.mutex)

  • 确保一次只能有一个代理执行浏览器操作
  • 默认TTL：30秒（可通过配置 MCP_ACTION_LOCK_TTL)
  • 代理工作时自动更新心跳
  • 代理最多等待60秒以获取锁（可通过以下方式配置 MCP_ACTION_LOCK_WAIT)

窗口注册表(<hash>.window_registry.json)

  • 跟踪哪个代理拥有哪个浏览器窗口
  • 包含：targetId、windowId、进程PID、上次心跳时间戳
  • 用于孤立清理：自动关闭崩溃/过时代理的窗口
  • 失效阈值：5分钟（可通过配置 MCP_WINDOW_REGISTRY_STALE_SECS)

启动静音(<hash>.startup.mutex)

  • 确保每个配置文件启动单个浏览器实例
  • 在初始Chrome进程启动协调期间使用

文件格式： 这 <hash> 是从您的Chrome配置文件中导出的SHA-256哈希 user_data_dir 和 profile_name，确保跨流程的稳定识别。

配置

您可以使用以下环境变量自定义锁行为：

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

孤儿窗清理

当代理启动浏览器会话时，它会自动：

  1. 检查窗口注册表中是否有来自死进程的条目（PID已不存在）
  2. 检查是否有过时的条目（>5分钟无心跳）
  3. 通过Chrome DevTools协议关闭孤立窗口
  4. 清理注册表项

这确保了崩溃或终止的代理不会让僵尸浏览器窗口打开。

演示视频（YouTube）

运行测试

我们不想使用pytest-asyncio。

pip install -e ".[test]"`

相关 MCP