# Selenium MCP Server

smithery badge

An MCP server that uses Selenium to interact with a WebDriver instance. Built using the [MCP-Server-Starter](https://github.com/TheSethRose/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:**
    ```bash
    git clone <your-repo-url> selenium-mcp-server
    cd selenium-mcp-server
    ```
2.  **Install dependencies:**
    ```bash
    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:**
    ```bash
    npm run build
    ```
5.  **Run the server:**
    ```bash
    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.

```typescript
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`:
    ```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](https://modelcontextprotocol.io/)
*   [Selenium WebDriver JS Documentation](https://www.selenium.dev/documentation/javascript/)
*   [MCP TypeScript SDK Documentation](https://modelcontextprotocol.io/sdk/typescript)

## 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>