selenium-mcp

Selenium MCP server for AI agents — 41 tools for real-browser automation: navigation, clicking, typing, assertions, screenshots, multi-session management, page snapshots with stable element refs, persistent selector hints, and batched multi-step execution.

Built with TypeScript, the official MCP SDK, and Selenium WebDriver — strict zod input validation, explicit waits, and structured responses designed for LLM agents.

One-Click Install

What's new in 0.3.0

• New tools: select_option for dropdowns, scroll (including infinite-scroll pages and scrollable panels), history for back, forward, and refresh, and wait_for_page to wait for a URL or title after a redirect.
• Responsive testing: window can now resize the viewport to an exact size, such as a 390x844 phone, or maximize it.
• Better tool choice by AI agents: every tool and parameter now explains what it does, what it returns, and when to use a similar tool instead.
• Breaking: open_url and wait_until_visible were removed as duplicates. Use navigate, and wait_for_element with visible: true.
• Verified releases: every release is tested end to end against a real browser and published with npm provenance.

See the changelog for details.

Setup

claude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest

Add to your client's MCP config (e.g. claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "selenium": {
      "command": "npx",
      "args": ["-y", "@gaforov/selenium-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"selenium","command":"npx","args":["-y","@gaforov/selenium-mcp@latest"]}'

goose session --with-extension "npx -y @gaforov/selenium-mcp@latest"

Settings → Tools → AI Assistant → Model Context Protocol → Add, with command npx and arguments -y @gaforov/selenium-mcp@latest. Full walkthrough in docs/CLIENT_INTEGRATION.md.

git clone https://github.com/gaforov/selenium-mcp.git
cd selenium-mcp
npm install
npm run build

Then point your MCP client at node /absolute/path/to/selenium-mcp/dist/server.js.

Example Usage

Ask your AI agent:

Use selenium-mcp to open Chrome, go to https://example.com, read the page title, take a screenshot, and close the browser.

The agent chains start_browser → navigate → get_title → take_screenshot → stop_browser on its own — no scripting needed.

Requirements

• Node.js 20+
• Chrome, Firefox, or Edge installed (Selenium Manager provisions the matching driver automatically)

How it compares

Most Selenium MCP servers wrap WebDriver's basic commands. This one adds the layer that makes agents reliable:

| Capability | selenium-mcp | Typical Selenium MCP servers | |---|:---:|:---:| | Page snapshot with stable element refs (capture_page) | ✅ | rare | | Persistent per-domain selector memory (selector_hint_*) | ✅ | ❌ | | Parallel multi-session browsing | ✅ | rare | | Batched multi-step execution in one call | ✅ | ❌ | | Built-in test assertions | ✅ | some | | Tool-call tracing (NDJSON audit log) | ✅ | ❌ | | Strict input validation + structured errors | ✅ | varies | | Every tool and parameter described for AI agents (enforced by tests) | ✅ | varies | | End-to-end tests against a real browser in CI | ✅ | some |

Why selenium-mcp

• Snapshot-first workflows — capture_page returns a page snapshot with stable element refs the agent can act on directly, no brittle selector guessing
• Selector hints — persist working locators per domain so repeat automations get faster and more reliable over time
• Batched execution — batch_execute runs constrained multi-step sequences in a single tool call, cutting round-trips
• Multi-session — create, select, list, and destroy parallel browser sessions
• Agent-friendly errors — every response is structured and validated with zod, so agents can recover instead of stalling
• Optional tracing — NDJSON trace of every tool call for debugging and auditing

Tools (41)

| Category | Tools | |---|---| | Browser lifecycle | start_browser, stop_browser, session_create, session_select, session_list, session_destroy | | Navigation | navigate, history (back/forward/refresh), wait_for_page (URL/title), get_current_url, get_title | | Element discovery | find_element, wait_for_element, capture_page, get_page_source | | Interaction | click, retry_click, interact (hover/double/right-click), type, select_option, scroll, press_key, upload_file | | Reading | get_text, get_attribute | | Assertions | assert_text, assert_visible, assert_attribute | | Scripting | execute_script, batch_execute | | Selector hints | selector_hint_save, selector_hint_get, selector_hint_list, selector_hint_delete | | Windows & context | window (tabs, windows, resize/maximize), frame, alert | | Cookies | add_cookie, get_cookies, delete_cookie | | Capture | take_screenshot |

Full parameter documentation: docs/TOOL_REFERENCE.md

MCP Resources

• browser-status://current — live browser/session status
• accessibility://current — accessibility snapshot of the current page

Optional Tracing

Enable lightweight NDJSON tracing of all tool calls:

SELENIUM_MCP_TRACE=true
SELENIUM_MCP_TRACE_PATH=./logs/selenium-mcp-trace.ndjson

If SELENIUM_MCP_TRACE_PATH is omitted, the default is logs/selenium-mcp-trace.ndjson.

Documentation

• Usage guide — prompts & recipes
• Tool reference
• Client integration
• Architecture
• Development guide
• Changelog
• Roadmap

Contributing

Contributions are welcome — bug reports, feature requests, and pull requests. See CONTRIBUTING.md to get started.

npm run typecheck
npm run build
npm test

License

MIT. See LICENSE.