Back to Directory/Testing & Quality

io.github.gaforov/selenium-mcp

Selenium MCP server for AI agents — 41 browser automation tools with snapshots and sessions.

Testing & QualityTypeScriptv0.3.0
View on GitHub

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.

npm version npm downloads CI license node

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

Install in Cursor Install in VS Code Install in VS Code Insiders

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

Capabilityselenium-mcpTypical 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)

CategoryTools
Browser lifecyclestart_browser, stop_browser, session_create, session_select, session_list, session_destroy
Navigationnavigate, history (back/forward/refresh), wait_for_page (URL/title), get_current_url, get_title
Element discoveryfind_element, wait_for_element, capture_page, get_page_source
Interactionclick, retry_click, interact (hover/double/right-click), type, select_option, scroll, press_key, upload_file
Readingget_text, get_attribute
Assertionsassert_text, assert_visible, assert_attribute
Scriptingexecute_script, batch_execute
Selector hintsselector_hint_save, selector_hint_get, selector_hint_list, selector_hint_delete
Windows & contextwindow (tabs, windows, resize/maximize), frame, alert
Cookiesadd_cookie, get_cookies, delete_cookie
Capturetake_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

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.

Installation

Source-derived launch command. Check the maintainer’s required arguments and credentials before running:

bash
npx -y @gaforov/selenium-mcp

Set up in your AI client

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

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

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Package

@gaforov/selenium-mcpnpm

Compatible MCP Clients

io.github.gaforov/selenium-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

  • Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.
  • Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.
  • VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.
  • Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.
  • Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

Learn More

Testing Your MCP Server: Inspector, Unit Tests, and CIMost MCP servers ship without a test strategy. MCPFind indexes 35 testing-category servers averaging just 0.3 stars. This guide covers three layers: interactive inspection, in-memory unit tests, and automated CI checks you can wire into GitHub Actions today.Read articlePlaywright MCP Server: Why Accessibility-Tree Automation Beats Screenshot-Based ApproachesMicrosoft's Playwright MCP server exposes 25+ browser automation tools to AI agents using the accessibility tree rather than screenshots. MCPFind indexes 82 testing servers. This guide covers setup, tool reference, and practical development use cases.Read article