What is Selenium Mcp Server

The selenium-mcp-server is an MCP server that utilizes Selenium to interact with a WebDriver instance, enabling AI agents to control web browser sessions for various automated tasks.

Use cases

Use cases include automated testing of web applications, scraping data from websites, filling out forms automatically, and performing repetitive tasks in a web browser.

How to use

To use selenium-mcp-server, clone the repository, install the necessary dependencies using npm, configure the WebDriver, build the server, and then run it. Optionally, it can be integrated with MCP hosts like Cursor or Claude Desktop.

Key features

Key features include exposing Selenium WebDriver actions as MCP tools, such as navigating to URLs, finding elements, clicking elements, sending keystrokes, and retrieving page source.

Where to use

Selenium-mcp-server can be used in fields such as web scraping, automated testing, and any scenario where web browser automation is required.

Selenium MCP Server

smithery badge

An MCP server that uses Selenium to interact with a WebDriver instance. Built using the MCP-Server-Starter template.

Overview

This server allows AI agents to control a web browser session via Selenium WebDriver, enabling tasks like web scraping, automated testing, and form filling through the Model Context Protocol.

Core Components

• MCP Server: Exposes Selenium WebDriver actions as MCP tools.
• Selenium WebDriver: Interacts with the browser.
• MCP Clients: AI hosts (like Cursor, Claude Desktop) that can utilize the exposed tools.

Prerequisites

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

Getting Started

1. Clone the repository:

   git clone <your-repo-url> selenium-mcp-server
   cd selenium-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure WebDriver:
   • Ensure your WebDriver (e.g., chromedriver) is installed and in your PATH.
   • Modify src/seleniumService.ts (you’ll create this file) if needed to specify browser options or WebDriver paths.
4. Build the server:

   npm run build
   

5. Run the server:

   npm start
   

   Alternatively, integrate it with an MCP host like Cursor or Claude Desktop (see Integration sections below).

Tools

This server will provide tools such as:

• selenium_navigate: Navigates the browser to a specific URL.
• selenium_findElement: Finds an element on the page using a CSS selector.
• selenium_click: Clicks an element.
• selenium_sendKeys: Sends keystrokes to an element.
• selenium_getPageSource: Retrieves the current page source HTML.
• (Add more tools as needed)

TypeScript Implementation

The server uses the @modelcontextprotocol/sdk and selenium-webdriver libraries.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { Builder, By, Key, until, WebDriver } from 'selenium-webdriver';

// Basic server setup (details in src/index.ts)
const server = new Server({
  name: "selenium-mcp-server",
  version: "0.1.0",
  capabilities: {
    tools: {}, // Enable tools capability
  }
});

// Selenium WebDriver setup (details in src/seleniumService.ts)
let driver: WebDriver;

async function initializeWebDriver() {
  driver = await new Builder().forBrowser('chrome').build(); // Or 'firefox', etc.
}

// Example tool implementation (details in src/tools/)
server.registerTool('selenium_navigate', {
  description: 'Navigates the browser to a specific URL.',
  inputSchema: { /* ... zod schema ... */ },
  outputSchema: { /* ... zod schema ... */ },
  handler: async (params) => {
    await driver.get(params.url);
    return { success: true };
  }
});

// Connect transport
async function startServer() {
  await initializeWebDriver();
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.log("Selenium MCP Server connected via stdio.");

  // Graceful shutdown
  process.on('SIGINT', async () => {
    console.log("Shutting down WebDriver...");
    if (driver) {
      await driver.quit();
    }
    process.exit(0);
  });
}

startServer();

Development

• Build: npm run build
• Run: npm start (executes node build/index.js)
• Lint: npm run lint
• Format: npm run format

Debugging

Use the MCP Inspector or standard Node.js debugging techniques.

Integration with MCP Hosts

(Keep relevant sections from the original README for Cursor, Claude Desktop, Smithery, etc., updating paths and commands as necessary)

Cursor Integration

1. Build your server: npm run build
2. In Cursor: Settings > Features > MCP: Add a new MCP server.
3. Register your server:
   • Select stdio as the transport type.
   • Name: Selenium Server (or similar).
   • Command: node /path/to/selenium-mcp-server/build/index.js.
4. Save.

Claude Desktop Integration

1. Build your server: npm run build
2. Modify claude_desktop_config.json:

   {
     "mcpServers": {
       "selenium-mcp-server": {
         "command": "node",
         "args": [
           "/path/to/selenium-mcp-server/build/index.js"
         ]
       }
     }
   }
   

3. Restart Claude Desktop.

Best Practices

• Use TypeScript and Zod for type safety and validation.
• Keep tools modular (e.g., one file per tool in src/tools/).
• Handle WebDriver errors gracefully (e.g., element not found, navigation issues).
• Ensure proper WebDriver shutdown (e.g., driver.quit() on server exit).
• Follow MCP best practices for schemas, error handling, and content types.

Learn More

• Model Context Protocol Documentation
• Selenium WebDriver JS Documentation
• MCP TypeScript SDK Documentation

Credits

Based on the template created by Seth Rose:

• Website: https://www.sethrose.dev
• 𝕏 (Twitter): https://x.com/TheSethRose
• 🦋 (Bluesky): https://bsky.app/profile/sethrose.dev