使用说明
# Selenium MCP Server
Selenium MCP Server is a standalone Python application that exposes a comprehensive suite of Selenium browser automation commands as a **FastMCP** server.
This allows a language model, AI agent, or any other client capable of calling tools to control a web browser, perform complex web scraping, and automate web-based tasks by issuing natural language commands.
## 🚀 Features
- **Browser Lifecycle**: Open and close Chrome, Firefox, or Edge instances.
- **Full Navigation**: `goto`, `back`, `forward`, `refresh`, and URL/title inspection.
- **Element Interaction**: `click`, `type`, `clear`, `get_text`, `get_attribute`.
- **Advanced Actions**: `hover`, `drag_and_drop`, `right_click`, `double_click`, `execute_javascript`.
- **Complex Targets**: Handles alerts, iframes, and Shadow DOM elements.
- **Data Extraction**: Scrape full tables into JSON, list all links, and get page source.
- **Window & Tab Management**: Open, close, and list all tabs.
- **Cookies & Storage**: Full control over browser cookies.
- **Explicit Waits**: Wait for elements to be visible or clickable to handle dynamic pages.
## 🔧 Dependencies and Installation
### Dependencies
This program relies on several third-party Python libraries:
- `fastmcp` – For creating the tool server
- `mcp-json` – For the JSON tool-calling schema with FastMCP
- `selenium` – For browser automation
- `webdriver-manager` – For automatically managing browser drivers (optional with Selenium 4.6+)
Create a `requirements.txt` file with the following content:
```txt
fastmcp
mcp-json
selenium
webdriver-manager
安装步骤
选项1：使用紫外线（推荐）
uv 是一个非常快速的Python包安装程序和虚拟环境管理器。
# 1. Create virtual environment
uv venv
# 2. Activate the environment
# macOS / Linux
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate
# 3. Install dependencies
uv pip install -r requirements.txt
选项2：使用venv+pip（传统）
# 1. Create virtual environment
# macOS / Linux
python3 -m venv venv
# Windows
python -m venv venv
# 2. Activate the environment
# macOS / Linux
source venv/bin/activate
# Windows
.\venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
浏览器驱动程序
现代版本的Selenium（4.6.0+）包括 硒经理，在您第一次运行该脚本时，它会自动为您本地安装的浏览器下载正确的web驱动程序（chromedriver、geckodriver等）。 无需手动安装驱动程序。
⚡️ Usage
运行主脚本以启动服务器：
python main.py
默认情况下，服务器运行中的所有浏览器 无头模式 （无可见UI）。这在
BrowserManager类。
输出示例：
Selenium MCP Server Starting...
Selenium MCP Server Running...
Supported Tools:
- open_browser, close_browser, goto_url, click_element, type_text, etc.
使用JSON配置运行（适用于mcp-JSON）
将服务器添加到您的 mcp-servers.json 配置：
{
"mcpServers": {
"Selenium Automation Server": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"path/to/your/selenium_mcp_server.py"
],
"env": {},
"transport": "stdio"
}
}
}
替换 path/to/your/selenium_mcp_server.py 使用服务器脚本的实际路径。
🛠 可用工具（API参考资料）
浏览器生命周期和导航
| 功能 | 说明 |
|---|---|
open_browser(browser_selector) |
打开一个新的浏览器实例(firefox, chrome, edge).默认为Firefox。 |
close_browser() |
关闭当前浏览器实例并清理资源。 |
is_browser_active() |
检查当前浏览器是否处于活动状态且响应良好。 |
goto_url(url) |
将浏览器导航到指定的URL |
get_current_url() |
返回当前页面的URL。 |
get_title() |
返回当前页面的标题。 |
refresh_page() |
刷新当前页面。 |
go_back() |
模拟浏览器的“后退”按钮。 |
go_forward() |
模拟浏览器的“前进”按钮。 |
元素交互
| 功能 | 说明 |
|---|---|
click_element(strategy, selector) |
单击由策略和选择器标识的元素。 |
type_text(text, strategy, selector, ...) |
在输入框中键入文本（可以先清除并按Enter键）。 |
get_element_text(strategy, selector) |
获取元素的可见文本。 |
get_element_attribute(attribute, ...) |
从元素获取属性（例如。， href, src). |
click_shadow_dom_element(host, element) |
单击Shadow DOM中的元素。 |
double_click_element(strategy, selector) |
对元素执行双击操作。 |
right_click_element(strategy, selector) |
执行右键单击（上下文单击）。 |
hover_element(strategy, selector) |
模拟将鼠标悬停在元素上。 |
drag_and_drop(source_selector, target_selector, ...) |
拖放元素。 |
数据和信息提取
| 功能 | 说明 |
|---|---|
get_page_source() |
返回当前页面的完整HTML源代码 <body>. |
extract_table_data(strategy, selector) |
提取表数据并将其作为JSON返回。 |
list_links() |
返回所有唯一链接的JSON列表（text+href）。 |
框架、警报和选项卡
| 功能 | 说明 |
|---|---|
handle_alert(accept, input_text) |
处理警报/提示（接受/拒绝、发送文本）。 |
switch_to_frame(selector, strategy) |
将上下文切换到iframe。 |
switch_to_default_content() |
返回主文档的上下文。 |
open_new_tab(url) |
打开一个新选项卡并切换到该选项卡 |
close_current_tab() |
关闭当前活动的选项卡 |
switch_tab(index) |
按索引切换到选项卡。 |
list_all_tabs() |
返回所有打开的选项卡的JSON列表（标题+URL）。 |
等待和验证
| 功能 | 说明 |
|---|---|
wait_for_element_visible(strategy, selector, timeout) |
等待元素出现并可见。 |
wait_for_element_clickable(strategy, selector, timeout) |
等待元素可点击。 |
is_element_visible(strategy, selector) |
检查元素当前是否可见（非遮挡）。 |
is_element_enabled(strategy, selector) |
检查元素是否已启用（非阻塞）。 |
Cookie和存储
| 功能 | 说明 |
|---|---|
get_cookies() |
以JSON格式返回当前域的所有Cookie。 |
add_cookie(name, value, path) |
在当前会话中添加一个简单的cookie。 |
delete_all_cookies() |
删除当前会话的所有Cookie。 |
高级和视觉
| 功能 | 说明 |
|---|---|
execute_javascript(script) |
执行自定义JavaScript并返回结果。 |
scroll_to(x, y) |
将窗口滚动到绝对坐标。 |
scroll_by(x, y) |
按特定数量滚动窗口。 |
take_screenshot(filename) |
截取视口屏幕截图（如果没有文件名，则返回base64）。 |
save_full_page_screenshot(filename) |
尝试捕获整个页面。 |
