MCP Selenium Server & Client

This project provides a Model Context Protocol (MCP) server and client implementation for Selenium-based browser automation. It allows LLMs or external tools to interact with a browser through a standardized protocol, supporting actions like navigation, input, and clicks.

🚀 Features

• MCP Server: Exposes Selenium browser automation as tools.

• MCP Client: Sends tool calls (e.g., navigate, click, input) and receives structured results.

• Extensible Actions: Modular design for actions (navigate, click, input). More actions to be added.

• Driver Management: Abstraction for Selenium sessions and locator strategies.

• Tool Facade: Unified interface for tools (mcp_tools, webtools).

• Logging & Context: Centralized log writer and execution context.

📂 Project Structure

.
├── client/
│   ├── client.py              # MCP client implementation
│   ├── llm_client.py          # Example LLM client integration (currently set to use Gemini)
│
├── server/
│   ├── mcp_selenium_server.py # MCP server entry point
│   ├── custom_context.py      # Execution context handling
│   ├── log_writer.py          # Logging utilities
│   ├── actions/               # Browser actions (navigate, click, input)
│   ├── engine/                # Driver/session/locator management
│   └── tools/                 # Tool definitions (MCP tools, web tools)
│
├── .env                       # Environment variables
├── pyproject.toml             # Project dependencies & configuration
├── uv.lock                    # Dependency lock file
├── LICENSE                    # License file
└── README.md                  # (this file)

⚙️ Installation

1. Clone the repo:

   git clone <repo-url>
   cd mcp-selenium

2. Install dependencies (using uv or poetry):

   uv sync

3. Set environment variables in .env if needed (e.g., LLM API Key).

▶️ Usage

Start the MCP Server

python server/mcp_selenium_server.py

Run the Client

python client/client.py

Example JSON-RPC Request

{
  "action": "launch_page",
  "args": {
    "url": "https://google.com",
    "browser": "edge",
    "headless": false
  }
}

Example Actions

• launch_page → Open a URL

• click → Click an element

• enter_text → Type text into a field At present only these actions are added but can be extended for more actions.

🛠 Development

• Python 3.10+

• Selenium WebDriver

• MCP protocol integration

Lint & format before committing:

uv run black .
uv run flake8 .

📜 License

This project is licensed under the terms of the MIT License.