PhungXuanAnh/selenium-mcp-server

---
A Model Context Protocol (MCP) server that provides web automation capabilities through Selenium WebDriver. This server allows AI assistants to interact with web pages by providing tools for navigation, element interaction, taking screenshots, and more.
1.1. Quick Start
1.1.1. Using Installed Package (Recommended)
1.1.2. Using Source Code (Development)
---
- 2. Features
- 3. Available Tools
- 3.1. Navigation and Page Management
- 3.2. Element Interaction
- 3.3. Element Styling
- 3.4. JavaScript Execution
- 3.5. Browser Logs
- 3.6. Local Storage Management
- 4. Installation
- 4.1. Prerequisites
- 4.2. Installation Options
- 4.2.1. Option A: Install as Python Package (Recommended)
- 4.2.2. Option B: Run from Source Code
- 4.3. Chrome Setup
- 5. Usage
- 5.1. Running the MCP Server
- 5.1.1. Option A: From Installed Package
- 5.1.2. Option B: From Source Code
- 5.2. Using MCP Inspector for Testing
- 5.2.1. Start Inspector Server
- 5.2.2. Access Inspector Interface
- 5.2.3. Command Line Options
- 5.3. Using with MCP Clients
- 5.3.1. Configuration Examples
- 5.3.2. Debug
- 6. Examples
- 6.1. Basic Web Automation
- 6.2. Advanced Usage
- 6.2.1. JavaScript Examples
- 7. Logging
- 8. Troubleshooting
- 8.1. Common Issues
- 8.1.1. Installation-Related Issues
- 8.1.2. Runtime Issues
- 8.1.3. Configuration Issues
- 9. Architecture
- 10. Contributing
- 11. Support
- 12. Documentation
- 13. Reference
2. Features
- **Web Navigation**: Navigate to URLs with timeout control and page readiness checking
- **Multiple Tabs**: List, open, switch, and close browser tabs by window handle
- **Element Discovery & Interaction**: Find elements by multiple criteria (text, class, ID, attributes, XPath) and interact with them through clicking and input value setting
- **Advanced Element Querying**: Get single elements, multiple elements with pagination, and direct child nodes with comprehensive filtering options
- **Screenshots**: Capture named PNG screenshots of the active tab in the default workspace location or an explicit output directory
- **Tab Video Recording**: Record one fixed tab or one MP4 that follows active-tab switches across selected tabs, optionally with a synthetic URL header
- **Element Styling**: Retrieve CSS styles and computed style information for any element
- **JavaScript Execution**: Execute custom JavaScript code in browser console with optional console output capture
- **Browser Logging**: Access console logs (with level filtering) and network request logs (with URL filtering and error filtering)
- **Local Storage Management**: Complete CRUD operations for browser local storage (add, read, update, delete)
- **iFrame Support**: Work with elements inside iframes using iframe ID or name targeting
- **XPath Support**: Use XPath expressions for precise element targeting
- **Chrome Browser Control**: Connect to existing Chrome instances or automatically start new ones
3. Available Tools
The default compact profile is documented in Compact Profile (Default).
The explicit --tool-profile legacy compatibility fallback provides the following 24
tools with their original names and call contracts.
3.1. Navigation and Page Management
- navigate(url, timeout) - Navigate to a specified URL with Chrome browser
- check_page_ready(wait_seconds) - Check if the current page is fully loaded with optional wait
- list_tabs() - List all browser tabs and identify the active tab
- open_tab(url=None) - Open a new tab and optionally navigate it to a URL
- switch_tab(handle) - Switch to a tab using a handle returned by list_tabs
- close_tab(handle=None) - Close a specific tab, or the active tab when no handle is provided
- take_screenshot(file_name, directory="tmp/selenium-screenshot") - Take a screenshot of the active tab. A descriptive file_name is required; .png is added when omitted. When the Agent knows its current workspace path, it should prefer an absolute directory inside that workspace so the destination does not depend on the MCP server cwd. Otherwise, omit directory to use the configured workspace default. Existing files receive a numeric suffix instead of being overwritten.
- record_video(action, file_name="", directory="tmp/selenium-video", include_address=false, window_handle="", max_duration_seconds=600, window_handles=[]) - start records one fixed window_handle, one MP4 following switches among 2-4 window_handles, or the active tab when both are omitted. The selectors are mutually exclusive. Always call stop immediately after the final browser action; the finite deadline auto-finalizes only as a fallback. Paths follow screenshot rules and include_address=true adds a synthetic URL header.