Mcp Selenium Haskell

mcp-selenium-haskell

一个使用 WebDriver 实现的 MCP Selenium 服务（Haskell），可通过 Claude 等标准化 MCP 客户端实现浏览器自动化。

致谢

本实现受到 Angie Jones 开发的 mcp-selenium 项目启发。感谢原项目贡献者为 MCP Selenium 自动化奠定基础。

与 mcp-selenium（Node.js）的比较

本项目是对原 JavaScript mcp-selenium 项目的 Haskell 重实现。以下是两种实现的客观比较：

目标受众与架构

• Node.js：直接集成 WebDriver，采用单会话模型
• Haskell：支持多会话，通过基于 UUID 的会话管理连接到 Selenium Grid

安装与依赖

• Node.js：发布到 npm，支持 npx，并包含浏览器管理功能
• Haskell：静态链接的可执行文件，需要单独安装 Selenium 服务

功能与 API

两种实现提供相同的 MCP 工具接口，但存在以下差异：

• Node.js：隐式会话管理（每个服务实例一个会话）
• Haskell：显式会话管理，支持并发会话

额外工具（仅 Haskell 提供）：

• 控制台日志套件：get_console_logs、inject_console_logger、get_injected_console_logs、get_available_log_types——全面监控 JavaScript 控制台
• 页面源代码：get_source——获取当前页面的 HTML
• 会话管理：基于 UUID 的会话 ID，实现完善的多会话隔离

测试与可靠性

• Node.js：基本测试覆盖
• Haskell：90 多项集成测试，包含全面验证

如何选择

如果你符合以下情况，请选择 Node.js mcp-selenium：

• 希望使用内置浏览器管理功能快速完成设置
• 更偏好 JavaScript 生态系统
• 只需要一个浏览器会话

如果你符合以下情况，请选择 Haskell mcp-selenium：

• 需要多个并发浏览器会话
• 希望获得类型安全和编译时错误检查
• 已有 Selenium Grid 基础设施
• 更偏好零依赖的可执行文件

当前状态

两种实现均已可用于生产环境，各有优势：

• Node.js：设置更快、生态系统成熟、部署更简单
• Haskell：支持多会话、类型安全、测试覆盖全面

请根据你的技术需求和生态系统偏好进行选择。

功能

• 使用基于 UUID 的会话 ID 管理多个浏览器会话
• 元素交互：单击、输入、悬停、拖放、双击、右键单击
• 使用 CSS 选择器、XPath、ID、名称、类、标签定位元素
• 支持注入和监控的 JavaScript 控制台日志记录
• 截取屏幕截图并获取页面源代码
• 支持文件上传
• 模拟键盘输入
• 支持 Chrome 和 Firefox 浏览器
• 无头模式运行
• 静态链接的可执行文件，无运行时依赖

API 文档

如需查看所有可用工具及其参数的完整文档，请参阅 API.md。

构建

nix develop
# inside the shell that will open...
cabal build

运行

通过 flake 运行

nix run github:albertov/mcp-selenium-haskell

通过发行版运行

mcp-selenium-hs

Claude Desktop 配置

如需将此 MCP 服务与 Claude Desktop 配合使用，请将以下配置添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "selenium": {
      "command": "mcp-selenium-hs",
      "args": [],
      "env": {
         "SELENIUM_HOST": "some.tailscale.host",
         "SELENIUM_PORT": "1234",
      }
    }
  }
}

或者通过 flake 配置

{
  "mcpServers": {
    "selenium": {
      "command": "nix",
      "args": ["run", "github:albertov/mcp-selenium-haskell"],
      "env": {
         "SELENIUM_HOST": "some.tailscale.host",
         "SELENIUM_PORT": "1234",
      }
    }
  }
}

配置文件通常位于：

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

添加此配置后，重启 Claude Desktop 即可启用 Selenium MCP 服务。

与 mcp-proxy 配合使用

mcp-proxy 可让你通过 HTTP/SSE 暴露 mcp-selenium 服务，以便远程访问，或连接到远程 MCP 服务。如果你希望让运行在不同机器上的 MCP 客户端通过网络访问 mcp-selenium 代理，这会很有用。只要配置好相应的环境变量（SELENIUM_HOST、SELENIUM_PORT 等）以连接 Selenium 服务，该服务可以位于任何位置。

⚠️ 安全警告

切勿在生产系统或不完全受你控制的网络中，将 mcp-proxy 绑定到 0.0.0.0！ 这会将 MCP 服务暴露给整个互联网，可能导致他人未经授权使用浏览器自动化功能。

安全的替代方案：

• Tailscale/VPN：绑定到 Tailscale 接口 IP（例如 --host=100.x.x.x）
• 本地 + SSH：使用 --host=127.0.0.1 和 SSH 端口转发（ssh -L 8080:localhost:8080 user@server）
• 专用网络：仅绑定到你控制的专用网络接口
• 防火墙：如果必须使用 0.0.0.0，请确保配置适当的防火墙规则以限制访问

通过 SSE 暴露 mcp-selenium（本地到远程）

要在 mcp-proxy 后运行 mcp-selenium，并通过 SSE 暴露以供远程访问：

# Install mcp-proxy
uv tool install mcp-proxy

# Run mcp-selenium behind the proxy on localhost (safe for local development)
mcp-proxy --port=8080 mcp-selenium-hs

# For network access, bind to a specific interface (replace with your Tailscale IP)
mcp-proxy --host=100.64.1.100 --port=8080 mcp-selenium-hs

# Or use SSH port forwarding for remote access
# On the server:
mcp-proxy --host=127.0.0.1 --port=8080 mcp-selenium-hs
# On the client:
# ssh -L 8080:localhost:8080 user@your-server

服务将在以下地址提供访问：

• SSE 端点：http://localhost:8080/sse
• 状态端点：http://localhost:8080/status

随后，你可以配置 Claude Desktop，使其连接到代理，而非直接连接到服务：

{
  "mcpServers": {
    "selenium-proxy": {
      "command": "mcp-proxy",
      "args": ["http://your-server:8080/sse"],
      "env": {}
    }
  }
}

多个命名服务

你可以使用不同配置运行多个 mcp-selenium 实例：

# Run multiple selenium instances with different headless settings
mcp-proxy --port=8080 \
  --named-server selenium-headless 'mcp-selenium-hs' \
  --named-server selenium-desktop 'mcp-selenium-hs'

这会暴露：

• 无头实例：http://localhost:8080/servers/selenium-headless/sse
• 桌面实例：http://localhost:8080/servers/selenium-desktop/sse

注意：浏览器类型（Chrome/Firefox）和其他选项通过 MCP 工具参数指定，而非环境变量。

使用配置文件

对于复杂的设置，请使用 JSON 配置文件：

{
  "mcpServers": {
    "selenium-default": {
      "command": "mcp-selenium-hs",
      "args": [],
      "transportType": "stdio"
    },
    "selenium-remote": {
      "command": "mcp-selenium-hs",
      "args": [],
      "env": {
        "SELENIUM_HOST": "selenium.example.com",
        "SELENIUM_PORT": "4444"
      },
      "transportType": "stdio"
    }
  }
}

然后运行：

mcp-proxy --port=8080 --named-server-config ./selenium-servers.json

Docker 部署

对于容器化部署，你可以通过 Docker 使用 mcp-proxy。出于安全考虑，务必绑定到特定接口：

FROM ghcr.io/sparfenyuk/mcp-proxy:latest

# Install dependencies and copy mcp-selenium-hs binary
RUN wget -O /usr/local/bin/mcp-selenium-hs https://github.com/albertov/mcp-selenium-haskell/releases/latest/download/mcp-selenium-hs
RUN chmod +x /usr/local/bin/mcp-selenium-hs

EXPOSE 8080
# Use a specific interface IP instead of 0.0.0.0
ENTRYPOINT ["mcp-proxy", "--host=127.0.0.1", "--port=8080", "mcp-selenium-hs"]

在 Docker 中集成 Tailscale：

# Run with Tailscale network access
docker run -d \
  --name mcp-selenium-proxy \
  --network=host \
  -e TAILSCALE_HOSTNAME=$(tailscale ip -4) \
  your-mcp-proxy-image \
  mcp-proxy --host=$(tailscale ip -4) --port=8080 mcp-selenium-hs

使用 Tailscale 安全访问网络

要以最安全的方式远程访问，请使用 Tailscale 创建安全网络：

1. 在服务端和客户端机器上安装 Tailscale
2. 获取服务端的 Tailscale IP：tailscale ip -4
3. 将 mcp-proxy 绑定到 Tailscale 接口并运行：

# Replace 100.64.1.100 with your actual Tailscale IP
mcp-proxy --host=100.64.1.100 --port=8080 mcp-selenium-hs

4. 配置 Claude Desktop，通过 Tailscale IP 连接：

{
  "mcpServers": {
    "selenium-proxy": {
      "command": "mcp-proxy",
      "args": ["http://100.64.1.100:8080/sse"],
      "env": {}
    }
  }
}

环境变量

使用 mcp-proxy 时，你可以传入环境变量以配置 Selenium 连接：

# Pass custom Selenium server configuration
mcp-proxy --port=8080 \
  --env SELENIUM_HOST selenium.example.com \
  --env SELENIUM_PORT 4444 \
  mcp-selenium-hs

支持的环境变量完整列表：

变量	默认值	说明	示例
SELENIUM_HOST	127.0.0.1	Selenium WebDriver 服务的主机名或 IP 地址	selenium.example.com
SELENIUM_PORT	4444	Selenium WebDriver 服务的端口号	4444

配置示例：

本地 Selenium 服务（默认）：

# These are the defaults, no configuration needed
export SELENIUM_HOST=127.0.0.1
export SELENIUM_PORT=4444

远程 Selenium Grid：

export SELENIUM_HOST=selenium-grid.company.com
export SELENIUM_PORT=4444

基于 Docker 的 Selenium：

export SELENIUM_HOST=selenium-container
export SELENIUM_PORT=4444

在不同端口运行的 Selenium：

export SELENIUM_HOST=localhost
export SELENIUM_PORT=8080

CORS 配置

要允许基于浏览器的客户端连接，你可以启用 CORS。使用通配符来源时请务必谨慎：

# ⚠️  Only use '*' for development/testing - NEVER in production!
mcp-proxy --port=8080 --allow-origin='*' mcp-selenium-hs

在生产环境中，务必指定确切的来源：

# Safe: specify exact origins you trust
mcp-proxy --port=8080 \
  --allow-origin='https://claude.ai' \
  --allow-origin='https://your-app.com' \
  mcp-selenium-hs

集成测试

本项目包含全面的黑盒集成测试，通过外部接口验证 MCP 服务的功能。

快速开始

运行所有集成测试：

./run_integration_tests.sh

此操作会自动：

1. 启动 selenium-server 守护进程
2. 启动用于测试夹具的 HTTP 服务
3. 构建 mcp-selenium-hs 可执行文件
4. 运行集成测试套件
5. 停止所有服务

文档

有关集成测试设置的详细信息，请参阅 integration_tests/README.md。

依赖项

项目使用以下关键依赖项：

• webdriver - Haskell 的 Selenium WebDriver 绑定
• hs-mcp - 模型上下文协议实现
• aeson - JSON 解析和编码

开发

前置条件

• GHC 9.10.2 或兼容版本
• Cabal 3.0+
• 用于集成测试：Python 3、pytest、selenium-server-standalone、chromium

Nix 环境

项目提供了包含所有依赖项的 Nix 环境：

nix-shell

或使用 flakes：

nix develop

测试

单元测试：

cabal test

集成测试：

./run_integration_tests.sh

代码质量

格式化代码：

nix fmt

检查代码质量并运行 lint：

nix check

许可证

BSD-3-Clause - 详情请参阅 LICENSE 文件。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 运行测试套件
6. 提交拉取请求

请确保所有测试均通过，且代码遵循项目的风格指南。