MCP Selenium
Enables browser automation using the Selenium WebDriver through MCP, supporting browser management, element location, and both basic and advanced user interactions.
README Documentation
MCP Selenium Server
A Model Context Protocol (MCP) server for Selenium WebDriver — browser automation for AI agents.
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)
goose session --with-extension "npx -y @angiejones/mcp-selenium@latest"
Claude Code
claude mcp add selenium -- npx -y @angiejones/mcp-selenium@latest
Cursor / Windsurf / other MCP clients
{
"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 --enableonce 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
git clone https://github.com/angiejones/mcp-selenium.git
cd mcp-selenium
npm install
Run Tests
npm test
Requires Chrome + chromedriver on PATH. Tests run headless.
Install via Smithery
npx -y @smithery/cli install @angiejones/mcp-selenium --client claude
Install globally
npm install -g @angiejones/mcp-selenium
mcp-selenium
License
MIT