{
  "markdown": "# selenium-mcp\n\nSelenium 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.\n\n[![npm version](https://img.shields.io/npm/v/%40gaforov%2Fselenium-mcp)](https://www.npmjs.com/package/@gaforov/selenium-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/%40gaforov%2Fselenium-mcp)](https://www.npmjs.com/package/@gaforov/selenium-mcp)\n[![CI](https://github.com/gaforov/selenium-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gaforov/selenium-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/%40gaforov%2Fselenium-mcp)](LICENSE)\n[![node](https://img.shields.io/node/v/%40gaforov%2Fselenium-mcp)](package.json)\n\nBuilt with TypeScript, the official MCP SDK, and Selenium WebDriver — strict zod input validation, explicit waits, and structured responses designed for LLM agents.\n\n### One-Click Install\n\n[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP_Server-black?style=flat-square)](https://cursor.com/en/install-mcp?name=selenium-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnYWZvcm92L3NlbGVuaXVtLW1jcEBsYXRlc3QiXX0%3D)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522selenium-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540gaforov%252Fselenium-mcp%2540latest%2522%255D%257D)\n[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522selenium-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540gaforov%252Fselenium-mcp%2540latest%2522%255D%257D)\n\n## Setup\n\n<details open>\n<summary><strong>Claude Code</strong></summary>\n\n```bash\nclaude mcp add selenium -- npx -y @gaforov/selenium-mcp@latest\n```\n</details>\n\n<details>\n<summary><strong>Claude Desktop / Cursor / Windsurf / other MCP clients</strong></summary>\n\nAdd to your client's MCP config (e.g. `claude_desktop_config.json` or `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"selenium\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@gaforov/selenium-mcp@latest\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\n```bash\ncode --add-mcp '{\"name\":\"selenium\",\"command\":\"npx\",\"args\":[\"-y\",\"@gaforov/selenium-mcp@latest\"]}'\n```\n</details>\n\n<details>\n<summary><strong>Goose</strong></summary>\n\n```bash\ngoose session --with-extension \"npx -y @gaforov/selenium-mcp@latest\"\n```\n</details>\n\n<details>\n<summary><strong>IntelliJ IDEA / JetBrains IDEs</strong></summary>\n\nSettings → Tools → AI Assistant → Model Context Protocol → Add, with command `npx` and arguments `-y @gaforov/selenium-mcp@latest`. Full walkthrough in [docs/CLIENT_INTEGRATION.md](docs/CLIENT_INTEGRATION.md).\n</details>\n\n<details>\n<summary><strong>From source</strong></summary>\n\n```bash\ngit clone https://github.com/gaforov/selenium-mcp.git\ncd selenium-mcp\nnpm install\nnpm run build\n```\n\nThen point your MCP client at `node /absolute/path/to/selenium-mcp/dist/server.js`.\n</details>\n\n## Example Usage\n\nAsk your AI agent:\n\n> Use selenium-mcp to open Chrome, go to https://example.com, read the page title, take a screenshot, and close the browser.\n\nThe agent chains `start_browser` → `navigate` → `get_title` → `take_screenshot` → `stop_browser` on its own — no scripting needed.\n\n## Requirements\n\n- Node.js 20+\n- Chrome, Firefox, or Edge installed (Selenium Manager provisions the matching driver automatically)\n\n## How it compares\n\nMost Selenium MCP servers wrap WebDriver's basic commands. This one adds the layer that makes agents *reliable*:\n\n| Capability | selenium-mcp | Typical Selenium MCP servers |\n|---|:---:|:---:|\n| Page snapshot with stable element refs (`capture_page`) | ✅ | rare |\n| Persistent per-domain selector memory (`selector_hint_*`) | ✅ | ❌ |\n| Parallel multi-session browsing | ✅ | rare |\n| Batched multi-step execution in one call | ✅ | ❌ |\n| Built-in test assertions | ✅ | some |\n| Tool-call tracing (NDJSON audit log) | ✅ | ❌ |\n| Strict input validation + structured errors | ✅ | varies |\n\n## Why selenium-mcp\n\n- **Snapshot-first workflows** — `capture_page` returns a page snapshot with stable element refs the agent can act on directly, no brittle selector guessing\n- **Selector hints** — persist working locators per domain so repeat automations get faster and more reliable over time\n- **Batched execution** — `batch_execute` runs constrained multi-step sequences in a single tool call, cutting round-trips\n- **Multi-session** — create, select, list, and destroy parallel browser sessions\n- **Agent-friendly errors** — every response is structured and validated with zod, so agents can recover instead of stalling\n- **Optional tracing** — NDJSON trace of every tool call for debugging and auditing\n\n## Tools (39)\n\n| Category | Tools |\n|---|---|\n| Browser lifecycle | `start_browser`, `stop_browser`, `session_create`, `session_select`, `session_list`, `session_destroy` |\n| Navigation | `open_url`, `navigate`, `get_current_url`, `get_title` |\n| Element discovery | `find_element`, `wait_for_element`, `wait_until_visible`, `capture_page`, `get_page_source` |\n| Interaction | `click`, `retry_click`, `interact` (hover/double/right-click), `type`, `press_key`, `upload_file` |\n| Reading | `get_text`, `get_attribute` |\n| Assertions | `assert_text`, `assert_visible`, `assert_attribute` |\n| Scripting | `execute_script`, `batch_execute` |\n| Selector hints | `selector_hint_save`, `selector_hint_get`, `selector_hint_list`, `selector_hint_delete` |\n| Windows & context | `window`, `frame`, `alert` |\n| Cookies | `add_cookie`, `get_cookies`, `delete_cookie` |\n| Capture | `take_screenshot` |\n\nFull parameter documentation: [docs/TOOL_REFERENCE.md](docs/TOOL_REFERENCE.md)\n\n## MCP Resources\n\n- `browser-status://current` — live browser/session status\n- `accessibility://current` — accessibility snapshot of the current page\n\n## Optional Tracing\n\nEnable lightweight NDJSON tracing of all tool calls:\n\n```bash\nSELENIUM_MCP_TRACE=true\nSELENIUM_MCP_TRACE_PATH=./logs/selenium-mcp-trace.ndjson\n```\n\nIf `SELENIUM_MCP_TRACE_PATH` is omitted, the default is `logs/selenium-mcp-trace.ndjson`.\n\n## Documentation\n\n- [Usage guide — prompts & recipes](docs/USAGE_GUIDE.md)\n- [Tool reference](docs/TOOL_REFERENCE.md)\n- [Client integration](docs/CLIENT_INTEGRATION.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Development guide](docs/DEVELOPMENT.md)\n- [Changelog](CHANGELOG.md)\n- [Roadmap](ROADMAP.md)\n\n## Contributing\n\nContributions are welcome — bug reports, feature requests, and pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\n```bash\nnpm run typecheck\nnpm run build\nnpm test\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 7113,
  "sha": "1f1b01d56a646a726e52f8112bd5c19417ad61f5011080dff3316f2ab53ebd07",
  "repo_slug": "gaforov/selenium-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gaforov_selenium_mcp_2f661b58/readme"
}