MCP Selenium

A Java implementation of the Model Context Protocol (MCP) for Selenium WebDriver, enabling browser automation through standardized MCP clients.

Overview

MCP Selenium provides a bridge between the Model Context Protocol and Selenium WebDriver. It allows AI assistants and other MCP-compatible clients to perform browser automation tasks using a standardized set of tools.

Project Structure

selenium-mcp/
├── src/
│   └── main/
│       └── java/
│           └── io/
│               └── github/
│                   └── naveenautomation/
│                       └── mcpselenium/
│                           ├── McpSeleniumServer.java       # The main MCP server implementation
│                           ├── McpSeleniumLauncher.java     # Launcher script for the server
│                           └── AdvancedMcpClient.java       # GUI client for testing
├── target/
│   └── mcp-selenium-0.1.0-jar-with-dependencies.jar         # Compiled JAR with dependencies
└── pom.xml                                                  # Maven project configuration

Prerequisites

• Java 11 or higher
• Maven (for building)
• Chrome or Firefox browser installed

Building the Project

# Clone the repository
git clone https://github.com/naveenautomation/selenium-mcp.git
cd selenium-mcp

# Build with Maven
mvn clean package

This will create the JAR file at target/mcp-selenium-0.1.0-jar-with-dependencies.jar.

Usage Options

Option 1: Command Line Usage

Starting the Server

Start the MCP Selenium server from the command line:

java -jar target/mcp-selenium-0.1.0-jar-with-dependencies.jar

The server will start and wait for commands on standard input. You’ll see the server information as initial output.

Sending Commands

You can now send JSON commands to the server. Type or paste the commands directly into the terminal, one per line.

Example Commands

1. Start a Chrome browser:

{"type":"tool_call","tool_call_id":"call-1","name":"start_browser","params":{"browser":"chrome","options":{"headless":false}}}

2. Navigate to a website:

{"type":"tool_call","tool_call_id":"call-2","name":"navigate","params":{"url":"https://www.example.com"}}

3. Find an element:

{"type":"tool_call","tool_call_id":"call-3","name":"find_element","params":{"by":"css","value":"h1"}}

4. Get element text:

{"type":"tool_call","tool_call_id":"call-4","name":"get_element_text","params":{"by":"css","value":"h1"}}

5. Click an element:

{"type":"tool_call","tool_call_id":"call-5","name":"click_element","params":{"by":"id","value":"submit-button"}}

6. Type text into an element:

{"type":"tool_call","tool_call_id":"call-6","name":"send_keys","params":{"by":"id","value":"search-box","text":"search query"}}

7. Take a screenshot:

{"type":"tool_call","tool_call_id":"call-7","name":"take_screenshot","params":{"outputPath":"screenshot.png"}}