readme.md•5.55 kB
# 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>