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

Terminal

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):

config.json

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

VS Code

bash

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

Goose

bash

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

bash

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_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 (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 status
accessibility://current — accessibility snapshot of the current page

Optional Tracing

Enable lightweight NDJSON tracing of all tool calls:

bash

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

Contributing

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

Terminal

npm run typecheck
npm run build
npm test

License

MIT. See LICENSE.