Selenium MCP Server

1Selenium MCP Server
2---
3 
4A 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.
5 
6## 1.1. Quick Start
7 
8### 1.1.1. Using Installed Package (Recommended)
9```bash
10# Install
11pip install mcp-server-selenium
12 
13# Run
14python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug
15```
16 
17### 1.1.2. Using Source Code (Development)
18```bash
19# Clone and setup
20git clone https://github.com/PhungXuanAnh/selenium-mcp-server.git
21cd selenium-mcp-server
22uv sync
23 
24# Run
25PYTHONPATH=src python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug
26```
27 
28---
29 
30- [2. Features](#2-features)
31- [3. Available Tools](#3-available-tools)
32  - [3.1. Navigation and Page Management](#31-navigation-and-page-management)
33  - [3.2. Element Interaction](#32-element-interaction)
34  - [3.3. Element Styling](#33-element-styling)
35  - [3.4. JavaScript Execution](#34-javascript-execution)
36  - [3.5. Browser Logs](#35-browser-logs)
37  - [3.6. Local Storage Management](#36-local-storage-management)
38- [4. Installation](#4-installation)
39  - [4.1. Prerequisites](#41-prerequisites)
40  - [4.2. Installation Options](#42-installation-options)
41    - [4.2.1. Option A: Install as Python Package (Recommended)](#421-option-a-install-as-python-package-recommended)
42    - [4.2.2. Option B: Run from Source Code](#422-option-b-run-from-source-code)
43  - [4.3. Chrome Setup](#43-chrome-setup)
44- [5. Usage](#5-usage)
45  - [5.1. Running the MCP Server](#51-running-the-mcp-server)
46    - [5.1.1. Option A: From Installed Package](#511-option-a-from-installed-package)
47    - [5.1.2. Option B: From Source Code](#512-option-b-from-source-code)
48  - [5.2. Using MCP Inspector for Testing](#52-using-mcp-inspector-for-testing)
49    - [5.2.1. Start Inspector Server](#521-start-inspector-server)
50    - [5.2.2. Access Inspector Interface](#522-access-inspector-interface)
51    - [5.2.3. Command Line Options](#523-command-line-options)
52  - [5.3. Using with MCP Clients](#53-using-with-mcp-clients)
53    - [5.3.1. Configuration Examples](#531-configuration-examples)
54    - [5.3.2. Debug](#532-debug)
55- [6. Examples](#6-examples)
56  - [6.1. Basic Web Automation](#61-basic-web-automation)
57  - [6.2. Advanced Usage](#62-advanced-usage)
58    - [6.2.1. JavaScript Examples](#621-javascript-examples)
59- [7. Logging](#7-logging)
60- [8. Troubleshooting](#8-troubleshooting)
61  - [8.1. Common Issues](#81-common-issues)
62    - [8.1.1. Installation-Related Issues](#811-installation-related-issues)
63    - [8.1.2. Runtime Issues](#812-runtime-issues)
64    - [8.1.3. Configuration Issues](#813-configuration-issues)
65- [9. Architecture](#9-architecture)
66- [10. Contributing](#10-contributing)
67- [11. Support](#11-support)
68- [12. Documentation](#12-documentation)
69- [13. Reference](#13-reference)
70 
71 
72# 2. Features
73 
74- **Web Navigation**: Navigate to URLs with timeout control and page readiness checking
75- **Element Discovery & Interaction**: Find elements by multiple criteria (text, class, ID, attributes, XPath) and interact with them through clicking and input value setting
76- **Advanced Element Querying**: Get single elements, multiple elements with pagination, and direct child nodes with comprehensive filtering options
77- **Screenshots**: Capture full-page screenshots of the current browser window
78- **Element Styling**: Retrieve CSS styles and computed style information for any element
79- **JavaScript Execution**: Execute custom JavaScript code in browser console with optional console output capture
80- **Browser Logging**: Access console logs (with level filtering) and network request logs (with URL filtering and error filtering)
81- **Local Storage Management**: Complete CRUD operations for browser local storage (add, read, update, delete)
82- **iFrame Support**: Work with elements inside iframes using iframe ID or name targeting
83- **XPath Support**: Use XPath expressions for precise element targeting
84- **Chrome Browser Control**: Connect to existing Chrome instances or automatically start new ones
85 
86# 3. Available Tools
87 
88The MCP server provides the following tools:
89 
90## 3.1. Navigation and Page Management
91- `navigate(url, timeout)` - Navigate to a specified URL with Chrome browser
92- `check_page_ready(wait_seconds)` - Check if the current page is fully loaded with optional wait
93- `take_screenshot()` - Take a screenshot of the current browser window
94 
95## 3.2. Element Interaction
96- `get_an_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath)` - Get an element identified by various criteria
97- `get_elements(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, page, page_size, return_html, xpath)` - Get multiple elements with pagination support
98- `get_direct_children(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath, page, page_size)` - Get all direct child nodes of an element with pagination
99- `click_to_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, element_index, xpath)` - Click on an element identified by various criteria
100- `set_value_to_input_element(text, class_name, id, attributes, element_type, input_value, in_iframe_id, in_iframe_name, xpath)` - Set a value to an input element
101 
102## 3.3. Element Styling
103- `get_style_an_element(text, class_name, id, attributes, element_type, in_iframe_id, in_iframe_name, return_html, xpath, all_styles, computed_style)` - Get style information for an element
104 
105## 3.4. JavaScript Execution
106- `run_javascript_in_console(javascript_code)` - Execute JavaScript code in the browser console
107- `run_javascript_and_get_console_output(javascript_code)` - Execute JavaScript code and capture both return value and console output
108 
109## 3.5. Browser Logs
110- `get_console_logs(log_level)` - Retrieve console logs from the browser with optional filtering by log level
111- `get_network_logs(filter_url_by_text, only_errors_log)` - Retrieve network request logs from the browser with optional filtering
112 
113## 3.6. Local Storage Management
114- `local_storage_add(key, string_value, object_value, create_empty_string, create_empty_object)` - Add or update a key-value pair in browser's local storage
115- `local_storage_read(key)` - Read a value from browser's local storage by key
116- `local_storage_read_all()` - Read all key-value pairs from browser's local storage
117- `local_storage_remove(key)` - Remove a key-value pair from browser's local storage
118- `local_storage_remove_all()` - Remove all key-value pairs from browser's local storage
119 
120# 4. Installation
121 
122## 4.1. Prerequisites
123 
124- Python 3.10 or higher
125- Chrome browser installed
126 
127## 4.2. Installation Options
128 
129You can use this MCP server in two ways:
130 
131### 4.2.1. Option A: Install as Python Package (Recommended)
132 
133Install directly from PyPI:
134```bash
135pip install mcp-server-selenium
136```
137 
138Or using uv:
139```bash
140uv add mcp-server-selenium
141```
142 
143### 4.2.2. Option B: Run from Source Code
144 
1451. Clone this repository:
146```bash
147git clone https://github.com/PhungXuanAnh/selenium-mcp-server.git
148cd selenium-mcp-server
149```
150 
1512. Install dependencies using uv:
152```bash
153uv sync
154```
155 
156Or using pip with virtual environment:
157```bash
158python -m venv .venv
159source .venv/bin/activate  # On Windows: .venv\Scripts\activate
160pip install -e .
161```
162 
163## 4.3. Chrome Setup
164 
165The MCP server can work with Chrome in two ways:
166 
1671. **Connect to existing Chrome instance** (recommended): Start Chrome with debugging enabled:
168```bash
169google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
170```
171 
1722. **Auto-start Chrome**: The server can automatically start Chrome if no instance is found.
173 
174# 5. Usage
175 
176## 5.1. Running the MCP Server
177 
178### 5.1.1. Option A: From Installed Package
179 
180After installing via pip/uv, you can run the server directly:
181 
182```bash
183# Basic usage with default settings
184python -m mcp_server_selenium
185 
186# With custom Chrome debugging port and user data directory
187python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug
188 
189# With verbose logging
190python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v
191 
192# Using the installed command (if available)
193selenium-mcp-server --port 9222 --user_data_dir /tmp/chrome-debug -v
194```
195 
196### 5.1.2. Option B: From Source Code
197 
198When running from source, ensure the Python path includes the src directory:
199 
200```bash
201# Navigate to the project directory
202cd /path/to/selenium-mcp-server
203 
204# Activate virtual environment (if using one)
205source .venv/bin/activate
206 
207# Run with proper Python path
208PYTHONPATH=src python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v
209 
210# Or using uv (recommended for development)
211uv run python -m mcp_server_selenium --port 9222 --user_data_dir /tmp/chrome-debug -v
212```
213 
214## 5.2. Using MCP Inspector for Testing
215 
216### 5.2.1. Start Inspector Server
217 
218For development and testing, you can use the MCP inspector:
219 
220**From Source Code:**
221```bash
222# Using uv (recommended)
223uv run mcp dev src/mcp_server_selenium/__main__.py
224 
225# Or with make command
226make inspector
227 
228# With custom options
229uv run mcp dev src/mcp_server_selenium/__main__.py --port 9222 --user_data_dir /tmp/chrome-debug --verbose
230```
231 
232**From Installed Package:**
233```bash
234# Create a wrapper script or use directly
235mcp dev python -m mcp_server_selenium
236```
237 
238### 5.2.2. Access Inspector Interface
239 
240Open your browser and navigate to: http://127.0.0.1:6274/#tools
241![](/images/image.png)
242 
243Check logs:
244```shell
245tailf /tmp/selenium-mcp.log
246```
247 
248### 5.2.3. Command Line Options
249 
250- `--port`: Chrome remote debugging port (default: 9222)
251- `--user_data_dir`: Chrome user data directory (default: auto-generated in /tmp)
252- `-v, --verbose`: Increase verbosity (use multiple times for more details)
253 
254## 5.3. Using with MCP Clients
255 
256The server communicates via stdio and follows the Model Context Protocol specification. You can integrate it with MCP-compatible AI assistants or clients.
257 
258### 5.3.1. Configuration Examples
259 
260**For Claude Desktop** (`claude_desktop_config.json`):
261 
262Using installed package:
263```json
264{
265  "mcpServers": {
266    "selenium": {
267      "command": "python",
268      "args": [
269        "-m", "mcp_server_selenium",
270        "--port", "9222",
271        "--user_data_dir", "/tmp/chrome-debug-claude"
272      ],
273      "env": {}
274    }
275  }
276}
277```
278 
279**For VS Code Copilot** (`.vscode/mcp.json`):
280 
281Using installed package:
282```json
283{
284  "servers": {
285    "selenium-installed": {
286      "command": "python",
287      "args": [
288        "-m", "mcp_server_selenium",
289        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp",
290        "--port=9225"
291      ]
292    }
293  }
294}
295```
296 
297Using source code directly:
298```json
299{
300  "servers": {
301    "selenium-source": {
302      "command": "/path/to/selenium-mcp-server/.venv/bin/python",
303      "args": [
304        "-m", "mcp_server_selenium",
305        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp-source",
306        "--port=9226"
307      ],
308      "env": {
309        "PYTHONPATH": "/path/to/selenium-mcp-server/src"
310      }
311    }
312  }
313}
314```
315 
316Alternative source code configuration using full path:
317```json
318{
319  "servers": {
320    "selenium-source-alt": {
321      "command": "/path/to/selenium-mcp-server/.venv/bin/python",
322      "args": [
323        "/path/to/selenium-mcp-server/src/mcp_server_selenium/__main__.py",
324        "--user_data_dir=/home/user/.config/google-chrome-selenium-mcp-alt",
325        "--port=9227"
326      ]
327    }
328  }
329}
330```
331 
332### 5.3.2. Debug
333 
334**VS Code Copilot MCP Status:**
335If you open the `.vscode/mcp.json` file, you can see the MCP server status at the bottom of VS Code.
336 
337![alt text](images/image1.png)
338 
339**View MCP Logs:**
340- In VS Code: Open Command Palette → "Developer: Show Logs..." → "MCP: selenium"
341- Check log file: `tail -f /tmp/selenium-mcp.log`
342 
343# 6. Examples
344 
345## 6.1. Basic Web Automation
346 
3471. **Navigate to a website**:
348   - Tool: `navigate`
349   - URL: `https://example.com`
350 
3512. **Take a screenshot**:
352   - Tool: `take_screenshot`
353   - Result: Screenshot saved to `~/selenium-mcp/screenshot/`
354 
3553. **Fill a form**:
356   - Tool: `fill_input`
357   - Selector: `#email`
358   - Text: `user@example.com`
359 
3604. **Click a button**:
361   - Tool: `click_element`
362   - Selector: `button[type="submit"]`
363 
3645. **Execute JavaScript**:
365   - Tool: `run_javascript_in_console`
366   - Code: `return document.title;`
367   - Result: Returns the page title
368 
3696. **JavaScript with console output**:
370   - Tool: `run_javascript_and_get_console_output`
371   - Code: `console.log('Hello from browser'); return window.location.href;`
372   - Result: Shows both console output and return value
373 
374## 6.2. Advanced Usage
375 
376- **Wait for dynamic content**: Use `wait_for_element` to wait for elements to load
377- **Get page information**: Use `get_page_title`, `get_current_url`, `get_page_content`
378- **Element inspection**: Use `get_element_text`, `get_element_attribute`, `check_element_exists`
379- **JavaScript automation**: Use `run_javascript_in_console` for complex DOM manipulation and data extraction
380- **JavaScript debugging**: Use `run_javascript_and_get_console_output` to capture console logs for debugging
381 
382### 6.2.1. JavaScript Examples
383 
384**Extract page data**:
385```javascript
386// Tool: run_javascript_in_console
387var links = Array.from(document.querySelectorAll('a')).slice(0, 5).map(a => ({
388    text: a.textContent.trim(),
389    href: a.href
390}));
391return links;
392```
393 
394**Page performance monitoring**:
395```javascript
396// Tool: run_javascript_and_get_console_output
397console.time('Page Analysis');
398var stats = {
399    title: document.title,
400    links: document.querySelectorAll('a').length,
401    images: document.querySelectorAll('img').length,
402    scripts: document.querySelectorAll('script').length
403};
404console.timeEnd('Page Analysis');
405console.log('Page stats:', stats);
406return stats;
407```
408 
409**Form automation**:
410```javascript
411// Tool: run_javascript_in_console
412document.querySelector('#username').value = 'testuser';
413document.querySelector('#password').value = 'password123';
414document.querySelector('#login-form').submit();
415return 'Form submitted successfully';
416```
417 
418# 7. Logging
419 
420The server logs all operations to `/tmp/selenium-mcp.log` with rotation. Use the `-v` flag to increase console verbosity:
421 
422- `-v`: INFO level logging
423- `-vv`: DEBUG level logging
424 
425# 8. Troubleshooting
426 
427## 8.1. Common Issues
428 
429### 8.1.1. Installation-Related Issues
430 
431**Package not found (installed package):**
432```bash
433# Verify installation
434pip list | grep mcp-server-selenium
435# or
436python -c "import mcp_server_selenium; print('OK')"
437```
438 
439**Module not found (source code):**
440```bash
441# Ensure PYTHONPATH is set correctly
442export PYTHONPATH=/path/to/selenium-mcp-server/src
443# or run from project root with:
444PYTHONPATH=src python -m mcp_server_selenium
445```
446 
447### 8.1.2. Runtime Issues
448 
4491. **Chrome not starting**: Ensure Chrome is installed and accessible from PATH
4502. **Port conflicts**: Use a different port with `--port` option
4513. **Permission errors**: Ensure the user data directory is writable
4524. **Element not found**: Increase wait times or use more specific selectors
4535. **JavaScript execution errors**: Check browser console for syntax errors or security restrictions
4546. **Console output not captured**: Ensure the JavaScript code runs successfully before checking console logs
455 
456### 8.1.3. Configuration Issues
457 
458**MCP Client Connection Problems:**
459- Verify the command path is correct (use `which python` to find Python executable)
460- For source code: Ensure PYTHONPATH environment variable is set
461- For installed package: Ensure the package is installed in the same Python environment as the MCP client
462- Check MCP client logs for detailed error messages
463 
464# 9. Architecture
465 
466- **FastMCP**: Uses the FastMCP framework for MCP protocol implementation
467- **Selenium WebDriver**: Chrome WebDriver for browser automation
468- **Synchronous Design**: All operations are synchronous for reliability
469- **Chrome DevTools Protocol**: Connects to Chrome via remote debugging protocol
470 
471# 10. Contributing
472 
4731. Fork the repository
4742. Create a feature branch
4753. Make your changes
4764. Add tests if applicable
4775. Submit a pull request
478 
479# 11. Support
480 
481For issues and questions:
482- Create an issue in the repository
483- Check the logs at `/tmp/selenium-mcp.log`
484- Use verbose logging for debugging
485 
486# 12. Documentation
487 
488For detailed documentation on specific features:
489- [JavaScript Console Tools](docs/javascript_console_tools.md) - Comprehensive guide for JavaScript execution tools
490- [Examples](examples/javascript_console_examples.py) - JavaScript execution examples and use cases
491 
492# 13. Reference
493 
494- https://github.com/modelcontextprotocol/python-sdk
495- https://github.com/modelcontextprotocol/servers
496