# MCP Selenium Server
A Model Context Protocol (MCP) server for Selenium WebDriver — browser automation for AI agents.
[](https://youtu.be/mRV0N8hcgYA)
## Setup
Goose (Desktop)
Paste into your browser address bar:
```
goose://extension?cmd=npx&arg=-y&arg=%40angiejones%2Fmcp-selenium%40latest&id=selenium-mcp&name=Selenium%20MCP&description=automates%20browser%20interactions
```
Goose (CLI)
```bash
goose session --with-extension "npx -y @angiejones/mcp-selenium@latest"
```
Claude Code
```bash
claude mcp add selenium -- npx -y @angiejones/mcp-selenium@latest
```
Cursor / Windsurf / other MCP clients
```json
{
"mcpServers": {
"selenium": {
"command": "npx",
"args": ["-y", "@angiejones/mcp-selenium@latest"]
}
}
}
```
## Example Usage
Tell the AI agent of your choice:
> Open Chrome, go to github.com/angiejones, and take a screenshot.
The agent will call Selenium's APIs to `start_browser`, `navigate`, and `take_screenshot`. No manual scripting or explicit directions needed.
## Supported Browsers
Chrome, Firefox, Edge, and Safari.
> **Safari note:** Requires macOS. Run `sudo safaridriver --enable` once and enable
> "Allow Remote Automation" in Safari → Settings → Developer. No headless mode.
---
Tools
### start_browser
Launches a browser session.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| browser | string | Yes | `chrome`, `firefox`, `edge`, or `safari` |
| options | object | No | `{ headless: boolean, arguments: string[] }` |
### navigate
Navigates to a URL.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes | URL to navigate to |
### interact
Performs a mouse action on an element.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | string | Yes | `click`, `doubleclick`, `rightclick`, or `hover` |
| by | string | Yes | Locator strategy: `id`, `css`, `xpath`, `name`, `tag`, `class` |
| value | string | Yes | Value for the locator strategy |
| timeout | number | No | Max wait in ms (default: 10000) |
### send_keys
Types text into an element. Clears the field first.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| by | string | Yes | Locator strategy |
| value | string | Yes | Locator value |
| text | string | Yes | Text to enter |
| timeout | number | No | Max wait in ms (default: 10000) |
### get_element_text
Gets the text content of an element.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| by | string | Yes | Locator strategy |
| value | string | Yes | Locator value |
| timeout | number | No | Max wait in ms (default: 10000) |
### get_element_attribute
Gets an attribute value from an element.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| by | string | Yes | Locator strategy |
| value | string | Yes | Locator value |
| attribute | string | Yes | Attribute name (e.g., `href`, `value`, `class`) |
| timeout | number | No | Max wait in ms (default: 10000) |
### press_key
Presses a keyboard key.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| key | string | Yes | Key to press (e.g., `Enter`, `Tab`, `a`) |
### upload_file
Uploads a file via a file input element.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| by | string | Yes | Locator strategy |
| value | string | Yes | Locator value |
| filePath | string | Yes | Absolute path to the file |
| timeout | number | No | Max wait in ms (default: 10000) |
### take_screenshot
Captures a screenshot of the current page.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| outputPath | string | No | Save path. If omitted, returns base64 image data. |
### close_session
Closes the current browser session. No parameters.
### execute_script
Executes JavaScript in the browser. Use for advanced interactions not covered by other tools (e.g., drag and drop, scrolling, reading computed styles, DOM manipulation).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| script | string | Yes | JavaScript code to execute |
| args | array | No | Arguments accessible via `arguments[0]`, etc. |
### window
Manages browser windows and tabs.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | string | Yes | `list`, `switch`, `switch_latest`, or `close` |
| handle | string | No | Window handle (required for `switch`) |
### frame
Switches focus to a frame or back to the main page.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | string | Yes | `switch` or `default` |
| by | string | No | Locator strategy (for `switch`) |
| value | string | No | Locator value (for `switch`) |
| index | number | No | Frame index, 0-based (for `switch`) |
| timeout | number | No | Max wait in ms (default: 10000) |
### alert
Handles browser alert, confirm, or prompt dialogs.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | string | Yes | `accept`, `dismiss`, `get_text`, or `send_text` |
| text | string | No | Text to send (required for `send_text`) |
| timeout | number | No | Max wait in ms (default: 5000) |
### add_cookie
Adds a cookie. Browser must be on a page from the cookie's domain.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | Yes | Cookie name |
| value | string | Yes | Cookie value |
| domain | string | No | Cookie domain |
| path | string | No | Cookie path |
| secure | boolean | No | Secure flag |
| httpOnly | boolean | No | HTTP-only flag |
| expiry | number | No | Unix timestamp |
### get_cookies
Gets cookies. Returns all or a specific one by name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Cookie name. Omit for all cookies. |
### delete_cookie
Deletes cookies. Deletes all or a specific one by name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | No | Cookie name. Omit to delete all. |
### diagnostics
Gets browser diagnostics captured via WebDriver BiDi (auto-enabled when supported).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| type | string | Yes | `console`, `errors`, or `network` |
| clear | boolean | No | Clear buffer after returning (default: false) |
Resources
MCP resources provide read-only data that clients can access without calling a tool.
### browser-status://current
Returns the current browser session status (active session ID or "no active session").
| Property | Value |
|----------|-------|
| MIME type | `text/plain` |
| Requires browser | No |
### accessibility://current
Returns an accessibility tree snapshot of the current page — a compact, structured JSON representation of interactive elements and text content. Much smaller than full HTML. Useful for understanding page layout and finding elements to interact with.
| Property | Value |
|----------|-------|
| MIME type | `application/json` |
| Requires browser | Yes |
---
Development
### Setup
```bash
git clone https://github.com/angiejones/mcp-selenium.git
cd mcp-selenium
npm install
```
### Run Tests
```bash
npm test
```
Requires Chrome + chromedriver on PATH. Tests run headless.
### Install via Smithery
```bash
npx -y @smithery/cli install @angiejones/mcp-selenium --client claude
```
### Install globally
```bash
npm install -g @angiejones/mcp-selenium
mcp-selenium
```
## License
MIT