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

Clone the repository:
git clone <your-repo-url> selenium-mcp-server cd selenium-mcp-server
Install dependencies:
npm install
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.
Build the server:
npm run build
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

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

Claude Desktop Integration

Build your server: npm run build
Modify claude_desktop_config.json:
{ "mcpServers": { "selenium-mcp-server": { "command": "node", "args": [ "/path/to/selenium-mcp-server/build/index.js" ] } } }
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

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

Integrations