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