Selenium MCP

Selenium MCP 服务

一个模型上下文协议（MCP）服务，使用连接到 browserless 服务的 Selenium WebDriver 提供浏览器自动化功能。此服务无需本地浏览器，通过 TCP 连接到 browserless，适用于可扩展的容器化部署。

功能

• 浏览器自动化：导航到 URL、与元素交互、执行 JavaScript
• Browserless 集成：通过 WebDriver 协议连接到 browserless 服务
• 异步 Python：使用 FastMCP 构建，支持高性能异步操作
• 适用于容器：基于 Alpine 的 Docker 镜像，无需本地浏览器
• 会话管理：为每个 MCP 上下文自动管理会话

快速开始

先决条件

• Python 3.13+
• 正在运行的 browserless 服务（本地或远程）
• UV 包管理器（推荐）

安装

# Clone the repository
git clone <your-repo-url>
cd selenium-mcp-server

# Install with UV
uv sync

# Or with pip
pip install -e .

环境设置

设置 browserless 服务 URL 和可选的身份验证令牌：

export BROWSERLESS_URL=http://localhost:3000  # Local browserless
export BROWSERLESS_URL=http://browserless:3000  # Kubernetes service

# Optional: Set authentication token if browserless requires it
export BROWSERLESS_TOKEN=your-bearer-token-here

运行服务

# With UV
uv run selenium-mcp

# Or directly
python -m selenium_mcp.server

Claude Desktop 设置

将以下内容添加到 Claude Desktop 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "selenium": {
      "command": "uv",
      "args": ["run", "selenium-mcp"],
      "env": {
        "BROWSERLESS_URL": "http://localhost:3000",
        "BROWSERLESS_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

可用工具

导航到 URL

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

查找元素

find_element({
  "selector": ".button-primary",
  "by": "css"  # css, xpath, id, name, class_name, tag_name, link_text, partial_link_text
})

点击元素

click_element({
  "selector": "#submit-button",
  "by": "id"
})

执行 JavaScript

execute_javascript({
  "script": "return document.title;"
})

截取屏幕截图

take_screenshot({})

获取页面信息

get_page_info({})

关闭浏览器

close_browser({})

Docker 部署

构建镜像

docker build -t selenium-mcp-server .

使用 Docker Compose 运行

version: '3.8'
services:
  browserless:
    image: browserless/chrome:latest
    ports:
      - "3000:3000"
    environment:
      - CONNECTION_TIMEOUT=60000
      - MAX_CONCURRENT_SESSIONS=10

  selenium-mcp:
    image: selenium-mcp-server:latest
    environment:
      - BROWSERLESS_URL=http://browserless:3000
      - BROWSERLESS_TOKEN=${BROWSERLESS_TOKEN:-}
    ports:
      - "8000:8000"
    depends_on:
      - browserless

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: selenium-mcp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: selenium-mcp
  template:
    metadata:
      labels:
        app: selenium-mcp
    spec:
      containers:
      - name: selenium-mcp
        image: selenium-mcp-server:latest
        env:
        - name: BROWSERLESS_URL
          value: "http://browserless-service:3000"
        - name: BROWSERLESS_TOKEN
          valueFrom:
            secretKeyRef:
              name: browserless-secrets
              key: token
        ports:
        - containerPort: 8000
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"

---
apiVersion: v1
kind: Service
metadata:
  name: browserless-service
spec:
  selector:
    app: browserless
  ports:
  - port: 3000
    targetPort: 3000

开发

虚拟环境

# Create virtual environment
uv venv .venv

# Activate on Unix/macOS
source .venv/bin/activate

# Activate on Windows
.venv\\Scripts\\activate

# Install dependencies
uv sync

测试

# Run tests
uv run pytest

# Start local browserless for testing
docker run -p 3000:3000 browserless/chrome:latest

# Test the server
BROWSERLESS_URL=http://localhost:3000 uv run selenium-mcp

代码检查与格式化

# Format code
uv run black src/

# Lint code
uv run ruff check src/

# Type checking
uv run mypy src/

GitHub CI/CD 流水线

此仓库包含一个 GitHub Actions 工作流，用于：

1. 测试：启动 browserless 容器并运行测试
2. 构建：使用 UV 创建 Docker 镜像
3. 推送：在 main 分支上部署到容器注册表

详情请参阅 .github/workflows/ci.yml。

环境变量

变量	描述	默认值
BROWSERLESS_URL	Browserless 服务 URL	必需
BROWSERLESS_TOKEN	用于 browserless 身份验证的可选 bearer 令牌	空
PYTHONPATH	用于导入的 Python 路径	/app/src
PYTHONUNBUFFERED	禁用缓冲的 Python 输出	1

Browserless 配置

此 MCP 服务需要 browserless 服务。建议的 browserless 配置如下：

docker run -p 3000:3000 \
  -e CONNECTION_TIMEOUT=60000 \
  -e MAX_CONCURRENT_SESSIONS=10 \
  -e DEFAULT_BLOCK_ADS=true \
  browserless/chrome:latest

性能注意事项

• 会话管理：每个 MCP 上下文都有自己的浏览器会话
• 连接池：Browserless 可处理多个并发会话
• 资源限制：在 Kubernetes 中设置适当的内存和 CPU 限制
• 超时：根据使用场景配置 browserless 超时

故障排除

常见问题

1. 连接被拒绝：确保 browserless 正在运行且可访问
2. 身份验证失败：检查是否需要 BROWSERLESS_TOKEN，以及是否已正确设置
3. 会话超时：增加 browserless 超时设置
4. 未找到元素：在脚本中使用适当的等待策略

日志

设置环境变量以启用调试日志：

export LOG_LEVEL=DEBUG
export BROWSERLESS_DEBUG=true

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 编写更改并添加测试
4. 提交拉取请求

支持

如有问题或疑问，请创建 GitHub issue，或查阅 browserless 文档。