Selenium MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Selenium MCP Server Navigate to example.com and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Selenium MCP Server
Model Context Protocol (MCP) server for Selenium WebDriver that enables AI agents and LLMs to control real browsers for automation
This project exposes Selenium WebDriver as an MCP (Model Context Protocol) server, allowing AI agents to control a real browser through structured tools.
It enables LLMs and autonomous agents to perform tasks like:
Opening browsers
Navigating websites
Discovering UI elements
Clicking buttons and links
Typing into inputs
Extracting page text
Taking screenshots
Many more future upgrades (in-progress)
This makes it possible to build AI-powered browser automation systems and autonomous QA agents.
Table of Contents
Related MCP server: Selenium MCP Server
WHY THIS PROJECT EXISTS
Modern AI agents need a way to interact with real applications.
While traditional automation tools like Selenium exist, they are not directly usable by LLM agents.
This project bridges that gap by exposing Selenium functionality through MCP tools so that agents can:
Understand web pages
Discover UI elements
Perform actions
Validate results
ARCHITECTURE
flowchart TD
A[LLM Agent] --> B[MCP Protocol]
B --> C[Selenium MCP Server]
C --> D[Browser Tools]
C --> E[Navigation Tools]
C --> F[Interaction Tools]
C --> G[Element Tools]
C --> H[Debug Tools]
D --> I[Selenium WebDriver]
E --> I
F --> I
G --> I
H --> I
I --> J[Browser]FEATURES
MCP-compatible Selenium automation server
Browser session management
Navigation controls
UI element discovery
Accessibility-aware interaction
Screenshot capture
Page text extraction
Headless browser support
Multi-tab browser management (open, switch, close, track active tab)
Improved interactive element detection for modern UI frameworks (React, Angular, dynamic DOM)
INSTALLATION
Run the following command
pip install selenium-mcpRUNNING THE SERVER
Start the MCP server
You can start the Selenium MCP server using different transport modes depending on your use case.
Default (STDIO)
selenium-mcp runUses stdio transport
Best for local agent integrations
No network exposure
HTTP Mode (Recommended)
selenium-mcp run --transport http --host 127.0.0.1 --port 3345Starts server at: http://127.0.0.1:3345
MCP endpoint: http://127.0.0.1:3345/mcp
Best for:
API integrations
Postman / curl testing
production-style usage
SSE Mode (Streaming)
selenium-mcp run --transport sse --host 127.0.0.1 --port 3345Starts server at: http://127.0.0.1:3345/sse
Best for:
streaming-based agents
real-time interactions
Note: Note: SSE endpoints are streaming and may not show output directly in the browser.
Expose Server on Network:
selenium-mcp run --transport http --host 0.0.0.0 --port 3345Makes server accessible from:
other devices on the same network
Docker / VM environments
Notes:
Default port: 3336
Supported transports:
stdio (default)
http
sseEnsure port is within range: 1–65535
MCP SERVER VERSION
To check the current version of the selenium MCP server, run the following command:
selenium-mcp versionAVAILABLE MCP TOOLS
Run the following command to get the list of tools supported by MCP server:
selenium-mcp tools This returns the list of tools supported by MCP server.
BROWSER CONTROL
open_browser– Launch a new browser sessionclose_browser– Close the browser sessionmaximize_browser– Maximize browser windowfullscreen_browser– Switch browser to fullscreen
NAVIGATION
open_url– Navigate to a specific URLnavigate_back– Navigate back in browser historynavigate_forward– Navigate forward in historyrefresh_page– Reload the pagewait_for_page– Wait for page to loadget_page_title– Get the current page title
TAB MANAGEMENT
get_tabs– Retrieve all open tabs in the current sessionswitch_tab– Switch to a specific tab using indexopen_new_tab– Open a new tab and optionally navigate to a URLclose_tab– Close a specific tab by indexget_current_tab– Retrieve the currently active tabname_tab– Assign a custom name to a tab for easier identification
These tools allow agents to manage multiple tabs within a single browser session.
ELEMENT DISCOVERY
get_interactive_elements– Discover visible interactive elements on the pageget_accessibility_tree– Retrieve simplified accessibility tree for the page
These tools allow agents to understand the UI structure before interacting with it.
Notes
Element detection is optimized for modern web applications (React, Angular, dynamic UI frameworks).
Elements are identified using interaction signals such as roles, click handlers, and focusability.
Only visible and meaningful elements are returned to reduce noise.
INTERACTION TOOLS
click_element– Click an element by indextype_into_element– Enter text into an input field
Elements must first be discovered using: get_interactive_elements
PAGE ANALYSIS
get_page_text – Extract visible text from the page
Useful for:
validation
reasoning
information extraction
VISUAL DEBUGGING
take_screenshot – Capture a screenshot of the current browser window
Screenshot Storage Location
When screenshots are captured, they are automatically saved in a hidden folder inside your home directory.
macOS / Linux
Screenshots are stored at:
~/.selenium-mcp/screenshotExample full path:
/Users/<your-username>/.selenium-mcp/screenshotYou can open the folder using Terminal:
open ~/.selenium-mcp/screenshotWindows
Screenshots are stored at:
C:\Users\<your-username>\.selenium-mcp\screenshotExample:
C:\Users\John\.selenium-mcp\screenshotYou can open it from File Explorer by entering the following in the address bar:
%USERPROFILE%\.selenium-mcp\screenshotCustom Screenshot Directory (Optional)
You can override the default screenshot location using the environment variable: SELENIUM_MCP_SCREENSHOT_DIR
macOS / Linux
export SELENIUM_MCP_SCREENSHOT_DIR=~/my-screenshotsWindows (PowerShell)
$env:SELENIUM_MCP_SCREENSHOT_DIR="C:\my-screenshots"All screenshots will then be saved to the specified directory.
Notes
The folder is created automatically the first time a screenshot is taken.
The
.selenium-mcpdirectory is hidden by default because it starts with a dot (.).You can safely delete screenshots anytime.
BROWSER SESSION FLOW
Each browser session is identified by a session_id.
Typical workflow for agents:
open_browser
open_url
wait_for_page
get_interactive_elements
(optional) get_tabs / switch_tab if multiple tabs are present
click_element or type_into_element
MULTI-TAB WORKFLOW
Agents can work with multiple tabs within the same browser session.
Example workflow:
open_browser
open_url
open_new_tab("https://example.com")
get_tabs
switch_tab(index)
perform actions
close_tab(index)
Notes
Each tab is tracked using an internal index.
The active tab is automatically managed and updated.
All actions are performed on the currently active tab.
EXAMPLE AGENT WORKFLOW
Example task:
Open Chrome browser.
Navigate to Google.com
Type the text "Selenium MCP" in the search box.
Press the search button
Agent steps:
open_browser
open_url("https://google.com")
wait_for_page
get_interactive_elements
type_into_element(index, "Selenium MCP")
click_element(index)
wait_for_page
get_page_textSYSTEM PROMPT FOR AI AGENTS
This repository includes a production-grade system prompt designed specifically for browser automation agents that interact with this Selenium MCP server.
The prompt contains detailed operational guidelines that instruct the AI agent on how to:
initialize and control the browser
discover and interact with UI elements
analyze page structure using the accessibility tree
avoid hallucinating element indexes
handle navigation and page reloads
recover from stale elements
follow a deterministic execution loop (PLAN → ACT → OBSERVE → UPDATE PLAN)
enforce safety limits on tool usage
Prompt location
prompts/system_prompt.mdHow to use
Whenever you build an AI agent that interacts with this MCP server, this prompt should be provided as the system prompt for the model.
Why this prompt
Browser automation agents can easily make incorrect decisions if not guided properly. This system prompt provides strict operational rules and guardrails that help the agent:
use MCP tools correctly
avoid incorrect element interactions
minimize hallucinations
perform reliable browser automation tasks
Using this prompt significantly improves the stability, accuracy, and reliability of AI-driven browser automation.
Recommendation
It is strongly recommended that all AI agents interacting with this Selenium MCP server use this system prompt to ensure consistent and reliable behavior.
PROMPT CUSTOMIZATION
You may modify or extend the system prompt depending on your use case. However, it is recommended to preserve the core operational rules related to:
MCP tool usage
element discovery
navigation handling
safety limits
LOGGING
All application logs are stored in a user-specific directory:
~/.selenium-mcp/logs/This directory is automatically created when the server starts.
Log file
Logs are written to:
~/.selenium-mcp/logs/selenium_mcp.logFeatures:
Daily log file rotation
Automatic cleanup of older log files
Logs written to both console and file
Persistent logs independent of the project directory
Logs are stored in the user's home directory so they remain available even if the package is installed globally via pip. This makes it easier to debug issues and monitor MCP server activity across different projects.
Example Log Entry
2026-03-15 19:00:07,444 [INFO] [selenium-mcp] Initializing Selenium MCP Server...macOS / Linux
Logs are stored in:
/Users/<username>/.selenium-mcp/logs/Example:
/Users/john/.selenium-mcp/logs/selenium_mcp.logYou can open it from the terminal:
cd ~/.selenium-mcp/logs
lsView logs:
cat selenium_mcp.logor
tail -f selenium_mcp.logWindows
Logs are stored in:
C:\Users\<username>\.selenium-mcp\logs\Example:
C:\Users\John\.selenium-mcp\logs\selenium_mcp.logOpen it in File Explorer:
C:\Users\%USERNAME%\.selenium-mcp\logs\Or from Command Prompt:
cd %USERPROFILE%\.selenium-mcp\logs
dirCONFIGURE YOUR MCP CLIENT
Add the Selenium MCP server to your MCP client configuration.
Example STDIO mode:
{
"mcpServers": {
"selenium-mcp": {
"command": "selenium-mcp"
}
}
}This tells the MCP client how to start the Selenium MCP server using stdio mode.
Example HTTP mode:
{
"mcpServers": {
"selenium-mcp": {
"command": "selenium-mcp",
"args": ["run", "--transport", "http", "host", "127.0.0.1", "--port", "3345"]
}
}
}Runs MCP server over HTTP
Endpoint: http://127.0.0.1:3345/mcp
Example SSE mode:
{
"mcpServers": {
"selenium-mcp": {
"command": "selenium-mcp",
"args": ["run", "--transport", "sse", "host", "127.0.0.1", "--port", "3345"]
}
}
}Runs MCP server with streaming (SSE) transport
Useful for real-time agent interactions
Endpoint: http://127.0.0.1:3345/sse
Client Examples
Claude Desktop
Config file location:
macOS
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows
%APPDATA%\Claude\claude_desktop_config.jsonSTDIO – Works for Claude Desktop
Add
{
"mcpServers": {
"selenium-mcp": {
"command": "selenium-mcp"
}
}
}Restart Claude Desktop after updating the configuration.
Uses stdio transport
Works out of the box with Claude Desktop
No additional configuration required
Troubleshooting
If you encounter issues while setting up or running Selenium MCP, try the following solutions.
selenium-mcp: command not found
This usually means the CLI command is not available in your system PATH.
First verify the package is installed:
pip show selenium-mcpLocate the installed command.
macOS / Linux
which selenium-mcpExample output:
/Users/<username>/.local/bin/selenium-mcpIf the command is found, update your MCP client configuration to use the full path:
{
"mcpServers": {
"selenium-mcp": {
"command": "/Users/<username>/.local/bin/selenium-mcp"
}
}
}Windows
Run:
where selenium-mcpExample output:
C:\Users\<username>\AppData\Roaming\Python\Python311\Scripts\selenium-mcp.exeUpdate your MCP client configuration:
{
"mcpServers": {
"selenium-mcp": {
"command": "C:\\Users\\<username>\\AppData\\Roaming\\Python\\Python311\\Scripts\\selenium-mcp.exe"
}
}
}Note: Windows paths in JSON require double backslashes (\\).
REQUIREMENTS
Python 3.10+
Web browser
USE CASES
This project can be used to build:
AI test automation agents
Autonomous QA assistants
LLM-powered browser copilots
Self-healing test frameworks
AI web scraping agents
Intelligent UI testing systems
CONTRIBUTING
Contributions are welcome.
Steps:
Fork the repository
Create a feature branch
Submit a pull request
LICENSE
MIT License
AUTHOR
Prashant Nayak
🔗 LinkedIn: https://www.linkedin.com/in/prashantjnayak
Built to help the QA and AI automation community build intelligent browser automation systems.
SUPPORT THE PROJECT
If this project helps you:
Star the repository
Share it with the QA community
Available Tools
22 toolsclick_elementA
Click an interactive element on the current webpage using its index.
Purpose
This tool allows the agent to click buttons, links, or other interactive
UI elements on the page. The element must first be discovered using
get_interactive_elements, which returns a list of visible elements and
assigns each one an index.
The index returned by get_interactive_elements must be used with this
tool to select the correct element.
Recommended Agent Workflow
Navigate to the desired page using
open_url.Wait for the page to load using
wait_for_page.Call
get_interactive_elementsto discover clickable elements.Review the returned elements and identify the correct one.
Call
click_elementusing the element's index.If navigation occurs after clicking, call
wait_for_pageagain.
Parameters
session_id : str
Active browser session identifier returned by open_browser.
index : int
Index of the element to click. This index must correspond to an
element returned by get_interactive_elements.
Returns
dict { "session_id": str "index": index of the element that was clicked, "status": str "message": str }
Error Conditions
If
get_interactive_elementshas not been called yet, the element cache will be empty and the tool will return an error.If the provided index does not exist in the cached elements list, the tool will return an "Invalid element index" error.
Notes
The tool automatically scrolls the element into view before clicking to ensure it is visible and interactable.
Inputs: index (required), session_id (required).
close_browserC
Close the browser session and free its resources.
Parameters
session_id : str Active browser session identifier.
Inputs: session_id (required).
close_tabA
Close a specific browser tab using its index.
Purpose
Allows the agent to close tabs that are no longer needed. After closing, focus automatically shifts to a valid remaining tab.
Parameters
session_id : str Active browser session identifier. index : int Index of the tab to close.
Returns
dict { "session_id": str, "status": str, "message": str }
Inputs: index (required), session_id (required).
fullscreen_browserC
Switch the browser to fullscreen mode.
Parameters
session_id : str Active browser session identifier.
Inputs: session_id (required).
get_accessibility_treeA
Retrieve a simplified accessibility tree of the current page.
Purpose
Returns interactive elements with semantic roles so AI agents
can understand UI meaning (buttons, links, inputs, dropdowns).
Returned index values map directly to click_element.
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id": str, "count": int, "nodes": [{"index": int, "role": str, "name": str, "tag": str, "id": str, "name_attr": str, "placeholder": str, "aria_label": str}], "status": str, "message": str }
Inputs: session_id (required).
get_current_tabA
Retrieve the currently active browser tab.
Purpose
Allows the agent to confirm which tab is currently active without listing all tabs.
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id": str, "status": str, "message": str, "tab": { "index": int, "name": str, "current": bool } }
Inputs: session_id (required).
get_interactive_elementsA
Retrieve visible interactive elements from the current web page.
Purpose
This tool scans the page for interactive elements using a performance-optimized selector that works across modern web applications (React, Angular, dynamic UIs).
It identifies elements based on interaction signals such as: - semantic HTML tags (button, input, link) - ARIA roles (button, link, tab, option) - click handlers (onclick) - focusable elements (tabindex)
The discovered elements are returned with an assigned index. This index
must be used when interacting with elements using tools such as:
- click_element
- type_into_element
The function also stores the discovered Selenium elements in an internal session cache so that subsequent tools can safely interact with the exact same elements without re-querying the DOM.
Recommended Agent Workflow
Navigate to a webpage using
open_url.Wait for the page to fully load using
wait_for_page.Call
get_interactive_elementsto discover UI elements.Review the returned list of elements and identify the correct element.
Use the provided
indexwith tools like:click_element(index)type_into_element(index, text)
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id": str, "count": int, "elements": [ { "index": int, "role": str, "label": str } ], "status": str, "message": str }
Notes
The returned
indexis required for all interaction tools.Only visible and meaningful elements are returned to reduce noise.
This tool is optimized for speed and avoids scanning the entire DOM.
Inputs: session_id (required).
get_page_textA
Retrieve visible text from the page body.
Purpose
Provides page text for reasoning, validation, or extraction.
Text is truncated to max_chars characters; check the returned
truncated flag to know whether content was cut.
Parameters
session_id : str Active browser session identifier. max_chars : int Maximum characters to return (default: 5000).
Returns
dict { "session_id": str, "page_text": str (Page text extract), truncated": bool (True, if the page_text is truncated. Else, False), "total_chars": int, "status": str, "message": str }
Inputs: session_id (required), max_chars.
get_page_titleB
Retrieve the title of the current web page.
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id: str, "page_title": str (title of the page), "status": str, "message": str }
Inputs: session_id (required).
get_tabsA
Retrieve all open browser tabs for the current session.
Purpose
Provides visibility into all tabs so the agent can decide which tab to switch to.
Each tab is identified by an index and optional name.
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id": str, "status": str, "message": str, "tabs": [ { "index": int, "name": str, "current": bool } ] }
Inputs: session_id (required).
maximize_browserC
Maximize the browser window.
Parameters
session_id : str Active browser session identifier.
Inputs: session_id (required).
name_tabA
Assign a custom name to a browser tab.
Purpose
Helps the agent label tabs meaningfully for easier navigation across multiple tabs.
Parameters
session_id : str Active browser session identifier. index : int Index of the tab to name. name : str Custom name to assign to the tab.
Returns
dict { "session_id": str, "status": str, "message": str }
Inputs: name (required), index (required), session_id (required).
open_browserA
Launch a new browser session.
Purpose
Creates a Selenium WebDriver instance and registers it in the MCP
session store. The returned session_id must be passed to all
subsequent browser tool calls.
Typical Agent Workflow
open_browser
open_url
wait_for_page
interact with elements
Parameters
browser : str Browser type to launch (default: "chrome"). headless : bool Run without a visible window (default: False). Set True on servers, Docker containers, or CI environments.
Returns
dict {"session_id": str, "browser": str, "headless": bool, "status": str, "message": str}
Note
Only call this tool ONCE per workflow, unless explicitly instructed. Do not call it again unless the previous browser session was closed.
Inputs: browser, headless.
open_new_tabA
Open a new browser tab and optionally navigate to a URL.
Purpose
Creates a new tab within the current browser session. The newly opened tab becomes the active tab.
Parameters
session_id : str Active browser session identifier. url : str, optional URL to open in the new tab. If not provided, a blank tab is opened.
Returns
dict { "session_id": str, "status": str, "message": str }
Inputs: session_id (required), url.
open_urlB
Navigate the browser to a specific URL.
Parameters
session_id : str Active browser session identifier. url : str Full URL to open (must include scheme, e.g. https://).
Inputs: url (required), session_id (required).
refresh_pageB
Reload the current web page.
Parameters
session_id : str Active browser session identifier.
Inputs: session_id (required).
switch_tabA
Switch to a specific browser tab using its index.
Purpose
Allows the agent to move between multiple open tabs in the same browser session.
Always call get_tabs first to understand available tab indexes.
Parameters
session_id : str Active browser session identifier. index : int Index of the tab to switch to.
Returns
dict { "session_id": str, "status": str, "message": str }
Inputs: index (required), session_id (required).
take_screenshotA
Capture a screenshot of the current browser window.
Purpose
Useful for debugging, failure reporting, or visual analysis. Screenshots are saved to the directory set by the MCP_SCREENSHOT_DIR environment variable (default: system temp dir).
Parameters
session_id : str Active browser session identifier.
Returns
dict { "session_id": str, screenshot_path: str, "status": str, "message": str }
Inputs: session_id (required).
type_into_elementA
Enter text into an input field or textarea using an element index.
Purpose
This tool allows the agent to type text into editable elements such as
input fields or textareas. The element must first be discovered using
get_interactive_elements, which returns a list of visible UI elements
along with their corresponding indexes.
The index returned by get_interactive_elements should be used directly
with this tool to identify which element to type into.
Recommended Agent Workflow
Call
get_interactive_elementsto retrieve all interactive elements.Identify the correct element by reviewing fields such as:
text
placeholder
aria_label
tag
Use the provided
indexto calltype_into_element.If the page changes after typing (e.g., search suggestions appear), consider calling
get_interactive_elementsagain.
Parameters
session_id : str
Active browser session identifier returned by open_browser.
index : int
Index of the element to type into. This must correspond to the index
returned by get_interactive_elements.
text : str The text to be entered into the selected element.
Returns
dict { "session_id": str, "index": index of the element used, "text_to_type": the text to enter, "status": str, "message": str }
Error Conditions
If get_interactive_elements has not been called previously,
the element cache may be empty and the tool will return an error.
Notes
This tool automatically clears any existing text in the element before entering the new text.
Inputs: text (required), index (required), session_id (required).
wait_for_pageA
Wait until the page body element is present in the DOM.
Purpose
Call after open_url or any navigation to give the page time
to load before attempting interactions.
Parameters
session_id : str Active browser session identifier. timeout : int Maximum seconds to wait (default: 10).
Returns
dict { "session_id": str, "timeout_set": timeout that was passed as a parameter, "status": str, "message": str }
Inputs: session_id (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools have clear distinct purposes, but get_interactive_elements and get_accessibility_tree serve similar functions (retrieving element info) with different output formats, which could cause agent confusion.
All tool names follow a consistent verb_noun snake_case pattern (e.g., open_browser, get_page_text, click_element), with no mixing of conventions.
22 tools cover the essential browser automation lifecycle and interactive actions without being excessive; the count is well-scoped for the server's purpose.
Covers core browsing workflows (navigation, tab management, element interaction, screenshots). Missing utilities like JavaScript execution, alert handling, or advanced element actions, but these are minor gaps.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Unofficial Hyperbrowser MCP — wraps the Hyperbrowser AI-agent browsing API (hyperbrowser.ai).…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for browser automation using Selenium WebDriver, enabling LLMs and teams to automate browsers with multi-browser support and a standard MCP API.54 npmMIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server for web automation using Selenium WebDriver, enabling AI assistants to navigate, interact with elements, take screenshots, and manage browser storage.15 PyPI10MIT
- AlicenseBqualityDmaintenanceA production-ready MCP server that exposes Selenium 4 browser automation as MCP tools.27MIT
- AlicenseNot gradedqualityDmaintenanceA Selenium-based MCP server that exposes browser automation tools for navigation, interaction, form filling, and assertions, enabling AI agents to control web browsers through natural language.1GPL 3.0