selenium-mcp
Selenium MCP server for AI agents — 39 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
Setup
Claude Code
claude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest
Claude Desktop / Cursor / Windsurf / other MCP clients
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"]
}
}
}
VS Code
code --add-mcp '{"name":"selenium","command":"npx","args":["-y","@gaforov/selenium-mcp@latest"]}'
Goose
goose session --with-extension "npx -y @gaforov/selenium-mcp@latest"
IntelliJ IDEA / JetBrains IDEs
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.
From source
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 |
Why selenium-mcp
- Snapshot-first workflows —
capture_pagereturns 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_executeruns 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 (39)
| Category | Tools |
|---|---|
| Browser lifecycle | start_browser, stop_browser, session_create, session_select, session_list, session_destroy |
| Navigation | open_url, navigate, get_current_url, get_title |
| Element discovery | find_element, wait_for_element, wait_until_visible, capture_page, get_page_source |
| Interaction | click, retry_click, interact (hover/double/right-click), type, 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, 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 statusaccessibility://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.