Selenium MCP

Selenium MCP Server

browserless サービスに接続された Selenium WebDriver を使用して、ブラウザー自動化機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーはローカルブラウザーなしで動作し、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 認証用の任意のベアラートークン	空
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. リポジトリをフォークします
2. 機能ブランチを作成します
3. テストを追加して変更を加えます
4. プルリクエストを送信します

サポート

問題や質問がある場合は、GitHub の issue を作成するか、browserless のドキュメントを確認してください。