selenium

The Selenium MCP Server exposes a set of MCP tools that allow AI agents to control a web browser via Selenium WebDriver. Tools such as selenium_navigate, selenium_findElement, selenium_click, selenium_sendKeys, and selenium_getPageSource enable navigation, element interaction, and data extraction inside an automated browsing session. Clients connecting to this MCP server can issue structured MCP requests to perform browser tasks, capture results, and handle common web automation scenarios with error handling and timeouts. The server is designed to be used with standard MCP hosts (like Cursor or Claude Desktop) and can be integrated via stdio transport or other MCP transports as configured in your deployment. To begin, start the server and connect through your MCP host using the provided build/index.js entry point, ensuring your WebDriver (ChromeDriver, GeckoDriver, etc.) is available on your system PATH.

Once connected, you can invoke tools such as navigate to a URL, locate elements with CSS selectors, perform clicks, send keystrokes to inputs, and retrieve the current page source for processing. The implementation emphasizes modular tool definitions, making it straightforward to add more Selenium-based capabilities as needed. The server uses the @modelcontextprotocol/sdk alongside selenium-webdriver to provide a robust and type-safe automation surface for AI agents.

Prerequisites:

• Node.js v18 or later
• npm v7 or later
• A WebDriver executable (e.g., ChromeDriver, GeckoDriver) installed and available in your PATH
• A compatible browser (e.g., Chrome, Firefox)

Installation steps:

1. Clone the repository git clone <your-repo-url> selenium-mcp-server cd selenium-mcp-server

2. Install dependencies npm install

3. Configure WebDriver (example)

   • Ensure chromedriver (or the chosen driver) is installed and in your PATH
   • Optionally modify src/seleniumService.ts to specify browser options or WebDriver paths

4. Build the server npm run build

5. Run the server npm start The server will listen for MCP connections and expose tools like selenium_navigate, selenium_findElement, selenium_click, selenium_sendKeys, and selenium_getPageSource.

Integration with MCP hosts (optional):

• Cursor or Claude Desktop can connect to the server using the stdio transport or an HTTP/WebSocket bridge depending on your setup. Configure the host to point at the built entry (build/index.js) as shown in the README examples.

Tips and notes:

• Ensure WebDriver is compatible with the browser you intend to automate and is accessible on PATH.
• Gracefully shut down the WebDriver on server exit to avoid orphaned processes (driver.quit()).
• Use modular tool implementations (one file per tool) to keep maintenance straightforward.
• Consider adding explicit error handling for common WebDriver errors (element not found, timeouts).
• When integrating with MCP hosts, keep tool descriptions, schemas, and responses consistent with MCP best practices, and validate inputs with Zod where applicable.
• If you need to expose more capabilities, you can extend the tool registry by adding new tools (e.g., selenium_waitFor, selenium_takeScreenshot) following the existing pattern.