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 で再実装したものです。2 つの実装を率直に比較します。

対象ユーザーとアーキテクチャ

• Node.js：WebDriver と直接連携する、単一セッションモデル
• Haskell：UUID ベースのセッション管理によるマルチセッション対応。Selenium Grid に接続します

インストールと依存関係

• Node.js：npx に対応して npm で公開されており、ブラウザー管理機能を含みます
• Haskell：静的リンクされた実行ファイルで、別途 Selenium サーバーが必要です

機能と API

どちらの実装も同じ MCP ツールインターフェースを提供しますが、次の違いがあります。

• Node.js：暗黙的なセッション管理（サーバーインスタンスごとに 1 セッション）
• 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 のエコシステムを利用したい
• ブラウザーセッションが 1 つ必要

次のような場合は 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 を使用すると、mcp-selenium サーバーを HTTP/SSE 経由で公開してリモートからアクセスしたり、リモート 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 を使用する必要がある場合は、適切なファイアウォールルールを設定してアクセスを制限してください

mcp-selenium を SSE 経由で公開する（ローカルからリモートへ）

mcp-selenium を mcp-proxy の背後で実行し、リモートアクセス用に 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. Tailscale インターフェースにバインドして mcp-proxy を実行します。

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

4. Tailscale IP を使って接続するよう Claude Desktop を設定します。

{
  "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 - Model Context Protocol の実装
• 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

コード品質を確認し、リンティングを実行します：

nix check

ライセンス

BSD-3-Clause - 詳細は LICENSE ファイルをご覧ください。

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 必要に応じてテストを追加します
5. テストスイートを実行します
6. プルリクエストを送信します

すべてのテストが合格し、コードがプロジェクトのスタイルガイドラインに従っていることを確認してください。