SeleniumBase MCP 服务器

将 SeleniumBase 浏览器自动化能力以工具的形式，通过 Model Context Protocol 暴露出来，这样任何 MCP 客户端（Claude Desktop、Claude Code 等）都可以驱动真实的浏览器。

本文件夹中有三种服务器变体：

三者默认均为 headless=False —— 除非你在启动会话时传入 headless=True，否则浏览器窗口是可见的。

将你的 MCP 客户端配置指向适合任务的 *_server.py（见下方第 3 步）—— 或者将三者以不同名称全部注册。

1. 安装

（需要 Python 3.10+ 和 uv）

git clone https://github.com/seleniumbase/seleniumbase-mcp.git
cd seleniumbase-mcp
uv sync

uv sync 会读取 pyproject.toml，在本文件夹中创建 .venv/，并安装两个依赖（mcp[cli]、seleniumbase）以及本项目本身 —— 这会通过 [project.scripts] 注册三个控制台脚本命令：

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

每个命令都只是调用对应服务器文件的 main() 函数（mcp.run(transport="stdio")）。这就是为什么 uv run <name> —— 无需 python 路径、无需 venv 路径、无需脚本路径 —— 就能作为第 3 步和第 4 步中的 MCP 客户端命令使用。

# SeleniumBase's Driver() and SB() formats need a browser driver downloaded:
uv run seleniumbase get chromedriver
# (Not needed for the "seleniumbase-cdp" Pure CDP Mode MCP Server,
#  which doesn't use WebDriver at all.)

（没有 uv？普通的 python3 -m venv venv && pip install -e . 也可以 —— 只需在下面所有地方用 python <script>.py 替代 uv run <name>，并在 MCP 客户端配置中使用绝对路径 venv/bin/python + 脚本路径，而不是无路径选项。）

Related MCP server: gotham-browser

2. 独立试用（可选，用于快速验证）

uv run mcp dev cdp_server.py

这会为 SeleniumBase 的“纯 CDP 模式”MCP 服务器打开 MCP Inspector，你可以在其中测试命令（“工具”）。按 Ctrl+C 退出。真正的测试是将其接入客户端（下一步）。

3. 连接到 Claude Desktop

Claude Desktop 不像 Claude Code 那样从“项目”目录运行，因此裸的 uv run <name> 不一定能找到本仓库。有两种方法可以获得稳定的配置：

选项 A —— 全局安装（推荐，任何地方都不需要路径）：

uv tool install .          # from inside the repo, installs the 3 commands globally

这会将 seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb 永久添加到你的 PATH 中（如果它警告其 bin 目录不在 PATH 上，请运行一次 uv tool ensurepath）。然后 claude_desktop_config.json 可以简化为：

{
  "mcpServers": {
    "seleniumbase-cdp": { "command": "seleniumbase-cdp" },
    "seleniumbase-driver": { "command": "seleniumbase-driver" },
    "seleniumbase-sb": { "command": "seleniumbase-sb" }
  }
}

选项 B —— 让 uv 直接指向仓库（一个绝对路径，但无需追踪 venv/解释器路径，也无需单独的安装步骤）：

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-sb"]
    }
  }
}

claude_desktop_config.json 的位置取决于你的系统：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

重启 Claude Desktop。你应该会看到 🔨 工具图标，表示服务器已连接，并且 start_browser、navigate、click 等工具可用。只保留你实际需要的条目 —— 如果你只需要一个，三个独立的浏览器自动化服务器就太多了。

4. 连接到 Claude Code

本仓库的 .mcp.json 已提交并可直接使用 —— 无需编辑路径，因为 uv run <name> 会从当前目录的 pyproject.toml 解析本项目：

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-sb"]
    }
  }
}

Claude Code 会从你启动 claude 的目录自动加载 .mcp.json，因此只要你在本仓库（或其克隆）内运行 claude，它就能正常工作 —— 对每个克隆仓库的队友来说都一样，无需任何机器特定的编辑。

如果你更愿意手动注册服务器，而不是依赖 .mcp.json：

claude mcp add seleniumbase-cdp -- uv run seleniumbase-cdp
claude mcp add seleniumbase-driver -- uv run seleniumbase-driver
claude mcp add seleniumbase-sb -- uv run seleniumbase-sb

（在仓库目录内运行，原因同上。）

暴露的工具（driver_server.py）

设计说明 / 需要根据你的使用场景调整的地方

• 单一全局会话。 每个服务器一次只持有一个浏览器会话。这与 MCP 服务器的典型启动方式（每个客户端连接一个进程）一致，也让工具表面保持简单。如果你需要多个并发浏览器标签页/会话，则需要将其扩展为命名会话的字典，并为每个工具添加 session_id 参数。

• 阻塞调用。 SeleniumBase 的调用是同步的，在页面加载或等待元素时会阻塞服务器。对于单用户本地工具来说没问题；对于多客户端服务器，你需要通过 asyncio.to_thread 在线程池中运行它们。

• 无头 vs 有头。 默认是有头（headless=False），这样你可以观察浏览器工作，并且阻止无头 Chrome 的网站也能正常运作。在确认流程可行后，为后台/服务器使用传入 headless=True。sb_server.py 的 uc=True（undetected-chromedriver）也有助于应对反爬墙。

扩展

添加一个工具只需添加一个带有 @mcp.tool() 装饰器的函数，调用对应的 SeleniumBase 方法即可 —— SeleniumBase 还有文件上传、悬停、警报、网络条件等方法，目前尚未包装。

cdp_server.py —— 纯 CDP 模式

包装 seleniumbase.sb_cdp.Chrome，这是 SeleniumBase 最隐蔽的模式：浏览器完全通过 Chrome DevTools 协议驱动，完全不涉及 WebDriver。参考文档： cdp_mode_methods.md。

工具分组

CDP 特定设计说明

• 元素不会以句柄的形式跨线传输。 在原生 CDP 模式中， find_element() 返回一个带有自身方法的活对象 （el.click()、el.get_html() 等）。MCP 工具只能返回 JSON 可序列化的数据，因此 find_element_info/find_all_info 会 立即将元素解析为普通字典（tag_name、text、html）， 而不是返回一个可以继续调用方法的句柄。如果 需要对多个匹配项中的某一个执行操作，请使用 click_nth_element（按位置操作）， 而不是将“查找，然后点击”作为两个独立步骤。

• 验证码解决并非万能。 solve_captcha 处理受支持的 挑战类型（例如 SeleniumBase 演示应用中的 Cloudflare Turnstile）； 它并不能保证绕过任意 CAPTCHA。

• 会话拆除。 sb.quit()（由 close_browser 使用）是 结束会话的文档化方式；如果进程在未调用它的情况下退出， 浏览器也会自动关闭。

• 未包含的内容： 基于 PyAutoGUI 的 gui_* 方法（设计上排除 —— 请参阅顶层设计说明）、底层管道 （get_websocket_url、add_handler、权限授予、原始 get_document/get_flattened_document）以及精确的方法别名 （open/goto 与 get）被省略以保持工具列表的聚焦 —— 如果你需要它们，可以像添加任何其他工具一样添加。

sb_server.py — 无需 with 语句的 SB()

包装 seleniumbase.SB()，通常用作上下文管理器：

with SB(uc=True) as sb:
    sb.goto(...)

MCP 服务器的工具调用是跨独立函数调用一次一个地进行的 —— 没有单一的缩进块可以放置 with —— 因此 该服务器改为手动调用上下文管理器协议：

sb_context = SB(**kwargs)
sb = sb_context.__enter__()   # in start_browser
...
sb_context.__exit__(None, None, None)   # in close_browser

sb 是一个 BaseCase 实例，是 SeleniumBase 最广泛的 API —— 是 Driver（在 driver_server.py 中）所暴露功能的超集， 外加 UC 模式隐身辅助功能和 driver_server.py/cdp_server.py 不具备的一些额外功能。该服务器 专注于这些额外功能，而不是重新包装已覆盖的所有内容：

另外还有与其他两个服务器相同的核心导航/交互/等待/断言/cookie/ 滚动/标签页/输出工具，通过 BaseCase 方法名调用（例如 sb.goto、sb.click、sb.assert_element）， 而不是通过 Driver 或 CDP 的方法。

SB() 特定设计说明

• UC 模式（隐身模式）需要在启动时设置 uc=True。 如果你需要这些功能，请在 start_browser 中预先传入。

• activate_cdp_mode 不会启动新会话。 它会将 现有 sb 会话的底层模式切换为 Pure CDP，以供后续 操作使用 —— 这是流程中途的升级，而不是全新的浏览器。