Selenium MCP Server

🚀 Selenium MCP Server

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

🚀 Quick Start

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.

✨ Features

• 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.

📦 Installation

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).

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:
   • 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).

💻 Usage Examples

Basic Usage

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)

Advanced Usage

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();

📚 Documentation

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

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