STARWARCLOUD STARWAR.AI
返回市场
MCP浏览器使用服务器

MCP浏览器使用服务器

作者：janspoerer6 星标更新：2025-10-29
安装使用来源：spider==github.com

项目介绍

【技术文档摘要】

MCP浏览器使用

在MseeP上验证

<img src="docs/mcp_browser_use_logo.jpg" alt="描述" width="300"> <br> <br> <br>

使用此MCP可以实现什么

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

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

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

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

功能亮点

  • HTML截断： 此MCP允许您配置HTML页面的截断。其他抓取MCP可能会用超出上下文窗口大小的可访问快照或HTML转储淹没AI。此MCP将帮助您通过设置MCP_MAX_SNAPSHOT_CHARS环境变量来管理最大页面大小。
  • 多个浏览器窗口和多个代理： 您可以独立地将多个代理连接到此MCP，而无需代理之间的协调。每个代理都可以使用相同的浏览器配置文件，这对于登录信息需要跨代理持久化的情况非常有用。每个代理都会获得自己的浏览器窗口，因此它们不会相互干扰。使用Chrome DevTools Protocol TargetId来识别浏览器窗口。

已知限制

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

配置/安装

  • 我们建议使用Chrome Canary或Chrome Beta。这将确保您的AI代理不会干扰您的Chrome实例。虽然此MCP可以处理任意数量的代理使用单个Chrome可执行文件，但MCP确实需要实例以开发者模式启动。如果您作为普通用户手动启动正常的Chrome实例，那么Chrome实例不会处于开发者模式。这是一个问题。因此，为了让您正常使用Chrome浏览器，请仅安装Chrome Beta（推荐）或Chrome Canary（由于不稳定不推荐）。
  • 安装Chrome Beta后，在.env文件中指向Chrome Beta可执行文件，如下所述。
  • 启动MCP服务器（如果您不知道如何操作，请参阅下面的“如何使用（此）MCP”部分）。

如何使用（此）MCP

请参阅modelcontextprotocol.io上的MCP文档。

请注意，您需要在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 Beta）

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

{
  "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": "1_0000"
      }
    }
  }
}

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_PATHChrome Beta可执行文件的路径见上面的示例
BETA_PROFILE_USER_DATA_DIRChrome Beta用户数据目录见上面的示例
CHROME_REMOTE_DEBUG_PORTChrome远程调试端口"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配置文件的user_data_dir和profile_name派生的SHA-256哈希，确保跨进程稳定标识。

配置

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

# 锁目录（默认：<project_root>/tmp/mcp_locks/）
MCP_BROWSER_LOCK_DIR=/path/to/locks

# 操作锁TTL（秒，默认：30）
MCP_ACTION_LOCK_TTL=30

# 操作锁最大等待时间（秒，默认：60）
MCP_ACTION_LOCK_WAIT=60

# 窗口注册表过时阈值（秒，默认：300）
MCP_WINDOW_REGISTRY_STALE_SECS=300

# 文件互斥过时阈值（秒，默认：60）
MCP_FILE_MUTEX_STALE_SECS=60

孤儿窗口清理

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

  1. 检查窗口注册表中来自死进程的条目（PID不再存在）
  2. 检查过时条目（超过5分钟没有心跳）
  3. 通过Chrome DevTools Protocol关闭孤儿窗口
  4. 清理注册表条目

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

演示视频（YouTube）

快速演示

运行测试

我们不希望使用pytest-asyncio。

pip install -e ".[test]"