Skip to main content
Glama
Selenium MCP Server

Selenium MCP Server

Selenium MCP Server

Python Selenium MCP Author

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

RUNNING 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 run
  • Uses stdio transport

  • Best for local agent integrations

  • No network exposure

selenium-mcp run --transport http --host 127.0.0.1 --port 3345

Starts 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 3345

Starts 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 3345

Makes server accessible from:

  • other devices on the same network

  • Docker / VM environments

Notes:

Default port: 3336 Supported transports:

stdio (default)
http
sse

Ensure 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 version

AVAILABLE 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

  1. open_browser – Launch a new browser session

  2. close_browser – Close the browser session

  3. maximize_browser – Maximize browser window

  4. fullscreen_browser – Switch browser to fullscreen

NAVIGATION

  1. open_url – Navigate to a specific URL

  2. navigate_back – Navigate back in browser history

  3. navigate_forward – Navigate forward in history

  4. refresh_page – Reload the page

  5. wait_for_page – Wait for page to load

  6. get_page_title – Get the current page title

TAB MANAGEMENT

  1. get_tabs – Retrieve all open tabs in the current session

  2. switch_tab – Switch to a specific tab using index

  3. open_new_tab – Open a new tab and optionally navigate to a URL

  4. close_tab – Close a specific tab by index

  5. get_current_tab – Retrieve the currently active tab

  6. name_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

  1. get_interactive_elements – Discover visible interactive elements on the page

  2. get_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

  1. click_element – Click an element by index

  2. type_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/screenshot

Example full path:

/Users/<your-username>/.selenium-mcp/screenshot

You can open the folder using Terminal:

open ~/.selenium-mcp/screenshot
Windows

Screenshots are stored at:

C:\Users\<your-username>\.selenium-mcp\screenshot

Example:

C:\Users\John\.selenium-mcp\screenshot

You can open it from File Explorer by entering the following in the address bar:

%USERPROFILE%\.selenium-mcp\screenshot

Custom 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-screenshots
Windows (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-mcp directory 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:

  1. open_browser

  2. open_url

  3. wait_for_page

  4. get_interactive_elements

  5. (optional) get_tabs / switch_tab if multiple tabs are present

  6. click_element or type_into_element

MULTI-TAB WORKFLOW

Agents can work with multiple tabs within the same browser session.

Example workflow:

  1. open_browser

  2. open_url

  3. open_new_tab("https://example.com")

  4. get_tabs

  5. switch_tab(index)

  6. perform actions

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

  1. Open Chrome browser.

  2. Navigate to Google.com

  3. Type the text "Selenium MCP" in the search box.

  4. 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_text

SYSTEM 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.md

How 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.log

Features:

  • 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.log

You can open it from the terminal:

cd ~/.selenium-mcp/logs
ls

View logs:

cat selenium_mcp.log

or

tail -f selenium_mcp.log

Windows

Logs are stored in:

C:\Users\<username>\.selenium-mcp\logs\

Example:

C:\Users\John\.selenium-mcp\logs\selenium_mcp.log

Open it in File Explorer:

C:\Users\%USERNAME%\.selenium-mcp\logs\

Or from Command Prompt:

cd %USERPROFILE%\.selenium-mcp\logs
dir

CONFIGURE 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"]
    }
  }
}

Example SSE mode:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "selenium-mcp",
      "args": ["run", "--transport", "sse", "host", "127.0.0.1", "--port", "3345"]
    }
  }
}

Client Examples

Claude Desktop

Config file location:

macOS
~/Library/Application Support/Claude/claude_desktop_config.json
Windows
%APPDATA%\Claude\claude_desktop_config.json
STDIO – 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-mcp

Locate the installed command.

macOS / Linux
which selenium-mcp

Example output:

/Users/<username>/.local/bin/selenium-mcp

If 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-mcp

Example output:

C:\Users\<username>\AppData\Roaming\Python\Python311\Scripts\selenium-mcp.exe

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

  1. Fork the repository

  2. Create a feature branch

  3. 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 tools
click_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.

  1. Navigate to the desired page using open_url.

  2. Wait for the page to load using wait_for_page.

  3. Call get_interactive_elements to discover clickable elements.

  4. Review the returned elements and identify the correct one.

  5. Call click_element using the element's index.

  6. If navigation occurs after clicking, call wait_for_page again.

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_elements has 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.

  1. Navigate to a webpage using open_url.

  2. Wait for the page to fully load using wait_for_page.

  3. Call get_interactive_elements to discover UI elements.

  4. Review the returned list of elements and identify the correct element.

  5. Use the provided index with 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 index is 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

  1. open_browser

  2. open_url

  3. wait_for_page

  4. 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.

  1. Call get_interactive_elements to retrieve all interactive elements.

  2. Identify the correct element by reviewing fields such as:

    • text

    • placeholder

    • aria_label

    • tag

  3. Use the provided index to call type_into_element.

  4. If the page changes after typing (e.g., search suggestions appear), consider calling get_interactive_elements again.

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

    A3.6/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    22 tools cover the essential browser automation lifecycle and interactive actions without being excessive; the count is well-scoped for the server's purpose.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers