# Selenium MCP Server
[](https://github.com/krishnapollu/selenium-mcp-server/actions/workflows/ci.yml)
[](https://badge.fury.io/py/selenium-mcp-server)
[](https://pypi.org/project/selenium-mcp-server/)
[](https://pypi.org/project/selenium-mcp-server/)
[](https://pypi.org/project/selenium-mcp-server/)
A powerful Model Context Protocol (MCP) server that brings Selenium WebDriver automation to AI assistants. This server enables AI tools like Claude Desktop and Cursor AI to control web browsers programmatically, making web automation accessible through natural language commands.
---
## 📚 Table of Contents
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Getting Started](#-getting-started)
- [Client Integration](#-client-integration)
- [Available Tools & Examples](#-available-tools--examples)
- [Advanced Configuration](#-advanced-configuration)
- [Environment Variables](#-environment-variables)
- [Testing Your Configuration](#-testing-your-configuration)
- [FAQ / Troubleshooting](#-faq--troubleshooting)
- [Contributing](#-contributing)
- [Changelog](#-changelog)
- [Project Structure](#project-structure)
- [License](#license)
- [Contact & Support](#contact--support)
---
## 🚀 Features
- Multi-browser support: Chrome and Firefox (headless or full mode)
- Session management: Start, list, switch, and close browser sessions
- Navigation: Go to URLs, reload, and retrieve page info
- Element interaction: Find, click, type, hover, drag-and-drop, double/right click, upload files
- Advanced actions: Execute JavaScript, take screenshots, get/set element text
- File operations: Upload files, download files, take full-page screenshots
- Robust error handling
- Easy integration with any MCP-compatible client (Cursor AI, Claude Desktop, Google Gemini, etc.)
- PEP 517/518 compliant packaging
---
## ⚡ Quick Start
```bash
pip install selenium-mcp-server
python -m selenium_mcp_server
```
Add this to your MCP client config (e.g., Cursor AI):
```json
{
"mcpServers": {
"selenium": {
"command": "python",
"args": ["-m", "selenium_mcp_server"]
}
}
}
```
---
## 🏁 Getting Started
1. **Install**
```bash
pip install selenium-mcp-server
```
2. **Run the server**
```bash
python -m selenium_mcp_server
```
3. **Connect your MCP client** (see config above)
**Windows users:** If you see a `.exe.deleteme` error, delete any `selenium-mcp-server.exe` or `.exe.deleteme` files in your Python `Scripts` directory, then retry the install. You can always run the server with `python -m selenium_mcp_server`.
---
## 🤖 Client Integration
- **Cursor AI:** `~/.cursor/mcp_config.json`
- **Claude Desktop:** `~/.config/claude-desktop/config.json` (Linux/macOS) or `%APPDATA%\claude-desktop\config.json` (Windows)
- **Other MCP Clients:** See your client's documentation
---
## 🛠️ Available Tools & Examples
### Browser Management
- **Start Browser**
```json
{ "browser": "chrome", "options": { "headless": true } }
```
- **List Sessions**
```json
{ "name": "list_sessions", "arguments": {} }
```
- **Switch Session**
```json
{ "session_id": "your-session-id" }
```
- **Close Session**
```json
{ "session_id": "your-session-id" }
```
### Navigation & Page Info
- **Navigate**
```json
{ "url": "https://example.com", "wait_for_load": true }
```
- **Get Page Info**
```json
{ "include_title": true, "include_url": true, "include_source": false }
```
### Element Interaction
- **Find Element**
```json
{ "selector": "#my-element", "selector_type": "css" }
```
- **Click Element**
```json
{ "selector": "#my-button", "selector_type": "css", "force_click": true }
```
- **Send Keys**
```json
{ "selector": "#input", "selector_type": "css", "text": "hello", "clear_first": true }
```
- **Get Element Text**
```json
{ "selector": "#output", "selector_type": "css" }
```
- **Hover**
```json
{ "selector": "#hover-target", "selector_type": "css" }
```
- **Drag and Drop**
```json
{ "selector": "#source", "selector_type": "css", "target_selector": "#target", "target_selector_type": "css" }
```
- **Double Click / Right Click**
```json
{ "selector": "#element", "selector_type": "css" }
```
- **Press Key**
```json
{ "key": "Enter" }
```
- **Upload File**
```json
{ "selector": "input[type='file']", "selector_type": "css", "filePath": "C:/Users/YourName/file.txt" }
```
- **Wait for Element**
```json
{ "selector": "#wait-for-me", "selector_type": "css", "wait_for_visible": true }
```
### Advanced Actions
- **Take Screenshot**
```json
{ "full_page": true }
```
- **Execute Script**
```json
{ "script": "return document.title;" }
```
---
## 📊 Example Automation Flow
```mermaid
flowchart TD
A["MCP Client (e.g., Cursor AI)"] -->|"Sends command"| B["Selenium MCP Server"]
B -->|"Controls"| C["Web Browser (Chrome/Firefox)"]
C -->|"Returns result"| B
B -->|"Responds via MCP"| A
```
---
## ⚙️ Advanced Configuration
You can configure the Selenium MCP Server in several ways:
### Option 1: Installed Package (Recommended)
```json
{
"mcpServers": {
"selenium": {
"command": "python",
"args": ["-m", "selenium_mcp_server"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
### Option 2: Direct File Execution
- **Windows:**
```json
{
"mcpServers": {
"selenium": {
"command": "python",
"args": ["C:\\path\\to\\selenium-mcp-server\\src\\selenium_mcp_server.py"],
"env": {
"PYTHONPATH": "C:\\path\\to\\selenium-mcp-server\\src",
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
- **macOS/Linux:**
```json
{
"mcpServers": {
"selenium": {
"command": "python",
"args": ["/path/to/selenium-mcp-server/src/selenium_mcp_server.py"],
"env": {
"PYTHONPATH": "/path/to/selenium-mcp-server/src",
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
### Option 3: Console Script
```json
{
"mcpServers": {
"selenium": {
"command": "selenium-mcp-server"
}
}
}
```
---
## 🌐 Environment Variables
- `PYTHONUNBUFFERED=1`: Ensures Python output is not buffered
- `SELENIUM_LOG_LEVEL=INFO`: Sets logging level (DEBUG, INFO, WARNING, ERROR)
- `PYTHONPATH`: Points to the directory containing the Python modules (needed for direct file execution)
---
## 🧪 Testing Your Configuration
After configuring, test with:
```json
{
"name": "list_sessions",
"arguments": {}
}
```
You should get an empty list if no sessions are active.
---
## ❓ FAQ / Troubleshooting
**Q: I see "0 tools enabled" in Cursor AI.**
- Make sure the package is installed: `pip install selenium-mcp-server` (or `pip install -e .` for development)
- Verify the module works:
```bash
python -c "import selenium_mcp_server; print('Module found!')"
```
- Check if the entry point works:
```bash
selenium-mcp-server --help
```
- Try using the console script entry point in your config.
**Q: "Module not found" errors**
- Make sure you've installed the package: `pip install selenium-mcp-server` or `pip install -e .`
- Check that the `PYTHONPATH` points to the correct directory if running from source
- Verify the file paths are correct for your system
**Q: "Command not found" errors**
- Ensure Python is in your system PATH
- Try using the full path to Python: `C:\Python312\python.exe` (Windows) or `/usr/bin/python3` (Linux/macOS)
**Q: Permission errors**
- On Windows, try running your MCP client as administrator
- On Linux/macOS, check file permissions: `chmod +x src/selenium_mcp_server.py`
Raw data
{
"_id": null,
"home_page": "https://github.com/krishnapollu/selenium-mcp-server",
"name": "selenium-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Krishna Pollu <your.email@example.com>",
"keywords": "selenium, webdriver, automation, mcp, model-context-protocol, ai, assistant",
"author": "Krishna Pollu",
"author_email": "Krishna Pollu <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/6a/20883c139ef527e790fea3ed034d3856c23881e7ebd1c5f39c24926f7cd9/selenium_mcp_server-1.2.0.tar.gz",
"platform": null,
"description": "# Selenium MCP Server\r\n\r\n[](https://github.com/krishnapollu/selenium-mcp-server/actions/workflows/ci.yml)\r\n[](https://badge.fury.io/py/selenium-mcp-server)\r\n[](https://pypi.org/project/selenium-mcp-server/)\r\n[](https://pypi.org/project/selenium-mcp-server/)\r\n[](https://pypi.org/project/selenium-mcp-server/)\r\n\r\nA powerful Model Context Protocol (MCP) server that brings Selenium WebDriver automation to AI assistants. This server enables AI tools like Claude Desktop and Cursor AI to control web browsers programmatically, making web automation accessible through natural language commands.\r\n\r\n---\r\n\r\n## \ud83d\udcda Table of Contents\r\n- [Features](#-features)\r\n- [Quick Start](#-quick-start)\r\n- [Getting Started](#-getting-started)\r\n- [Client Integration](#-client-integration)\r\n- [Available Tools & Examples](#-available-tools--examples)\r\n- [Advanced Configuration](#-advanced-configuration)\r\n- [Environment Variables](#-environment-variables)\r\n- [Testing Your Configuration](#-testing-your-configuration)\r\n- [FAQ / Troubleshooting](#-faq--troubleshooting)\r\n- [Contributing](#-contributing)\r\n- [Changelog](#-changelog)\r\n- [Project Structure](#project-structure)\r\n- [License](#license)\r\n- [Contact & Support](#contact--support)\r\n\r\n---\r\n\r\n## \ud83d\ude80 Features\r\n- Multi-browser support: Chrome and Firefox (headless or full mode)\r\n- Session management: Start, list, switch, and close browser sessions\r\n- Navigation: Go to URLs, reload, and retrieve page info\r\n- Element interaction: Find, click, type, hover, drag-and-drop, double/right click, upload files\r\n- Advanced actions: Execute JavaScript, take screenshots, get/set element text\r\n- File operations: Upload files, download files, take full-page screenshots\r\n- Robust error handling\r\n- Easy integration with any MCP-compatible client (Cursor AI, Claude Desktop, Google Gemini, etc.)\r\n- PEP 517/518 compliant packaging\r\n\r\n---\r\n\r\n## \u26a1 Quick Start\r\n\r\n```bash\r\npip install selenium-mcp-server\r\npython -m selenium_mcp_server\r\n```\r\n\r\nAdd this to your MCP client config (e.g., Cursor AI):\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"selenium\": {\r\n \"command\": \"python\",\r\n \"args\": [\"-m\", \"selenium_mcp_server\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udfc1 Getting Started\r\n\r\n1. **Install**\r\n ```bash\r\n pip install selenium-mcp-server\r\n ```\r\n2. **Run the server**\r\n ```bash\r\n python -m selenium_mcp_server\r\n ```\r\n3. **Connect your MCP client** (see config above)\r\n\r\n**Windows users:** If you see a `.exe.deleteme` error, delete any `selenium-mcp-server.exe` or `.exe.deleteme` files in your Python `Scripts` directory, then retry the install. You can always run the server with `python -m selenium_mcp_server`.\r\n\r\n---\r\n\r\n## \ud83e\udd16 Client Integration\r\n\r\n- **Cursor AI:** `~/.cursor/mcp_config.json`\r\n- **Claude Desktop:** `~/.config/claude-desktop/config.json` (Linux/macOS) or `%APPDATA%\\claude-desktop\\config.json` (Windows)\r\n- **Other MCP Clients:** See your client's documentation\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0f Available Tools & Examples\r\n\r\n### Browser Management\r\n- **Start Browser**\r\n ```json\r\n { \"browser\": \"chrome\", \"options\": { \"headless\": true } }\r\n ```\r\n- **List Sessions**\r\n ```json\r\n { \"name\": \"list_sessions\", \"arguments\": {} }\r\n ```\r\n- **Switch Session**\r\n ```json\r\n { \"session_id\": \"your-session-id\" }\r\n ```\r\n- **Close Session**\r\n ```json\r\n { \"session_id\": \"your-session-id\" }\r\n ```\r\n\r\n### Navigation & Page Info\r\n- **Navigate**\r\n ```json\r\n { \"url\": \"https://example.com\", \"wait_for_load\": true }\r\n ```\r\n- **Get Page Info**\r\n ```json\r\n { \"include_title\": true, \"include_url\": true, \"include_source\": false }\r\n ```\r\n\r\n### Element Interaction\r\n- **Find Element**\r\n ```json\r\n { \"selector\": \"#my-element\", \"selector_type\": \"css\" }\r\n ```\r\n- **Click Element**\r\n ```json\r\n { \"selector\": \"#my-button\", \"selector_type\": \"css\", \"force_click\": true }\r\n ```\r\n- **Send Keys**\r\n ```json\r\n { \"selector\": \"#input\", \"selector_type\": \"css\", \"text\": \"hello\", \"clear_first\": true }\r\n ```\r\n- **Get Element Text**\r\n ```json\r\n { \"selector\": \"#output\", \"selector_type\": \"css\" }\r\n ```\r\n- **Hover**\r\n ```json\r\n { \"selector\": \"#hover-target\", \"selector_type\": \"css\" }\r\n ```\r\n- **Drag and Drop**\r\n ```json\r\n { \"selector\": \"#source\", \"selector_type\": \"css\", \"target_selector\": \"#target\", \"target_selector_type\": \"css\" }\r\n ```\r\n- **Double Click / Right Click**\r\n ```json\r\n { \"selector\": \"#element\", \"selector_type\": \"css\" }\r\n ```\r\n- **Press Key**\r\n ```json\r\n { \"key\": \"Enter\" }\r\n ```\r\n- **Upload File**\r\n ```json\r\n { \"selector\": \"input[type='file']\", \"selector_type\": \"css\", \"filePath\": \"C:/Users/YourName/file.txt\" }\r\n ```\r\n- **Wait for Element**\r\n ```json\r\n { \"selector\": \"#wait-for-me\", \"selector_type\": \"css\", \"wait_for_visible\": true }\r\n ```\r\n\r\n### Advanced Actions\r\n- **Take Screenshot**\r\n ```json\r\n { \"full_page\": true }\r\n ```\r\n- **Execute Script**\r\n ```json\r\n { \"script\": \"return document.title;\" }\r\n ```\r\n\r\n---\r\n\r\n## \ud83d\udcca Example Automation Flow\r\n\r\n```mermaid\r\nflowchart TD\r\n A[\"MCP Client (e.g., Cursor AI)\"] -->|\"Sends command\"| B[\"Selenium MCP Server\"]\r\n B -->|\"Controls\"| C[\"Web Browser (Chrome/Firefox)\"]\r\n C -->|\"Returns result\"| B\r\n B -->|\"Responds via MCP\"| A\r\n```\r\n\r\n---\r\n\r\n## \u2699\ufe0f Advanced Configuration\r\n\r\nYou can configure the Selenium MCP Server in several ways:\r\n\r\n### Option 1: Installed Package (Recommended)\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"selenium\": {\r\n \"command\": \"python\",\r\n \"args\": [\"-m\", \"selenium_mcp_server\"],\r\n \"env\": {\r\n \"PYTHONUNBUFFERED\": \"1\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Option 2: Direct File Execution\r\n- **Windows:**\r\n ```json\r\n {\r\n \"mcpServers\": {\r\n \"selenium\": {\r\n \"command\": \"python\",\r\n \"args\": [\"C:\\\\path\\\\to\\\\selenium-mcp-server\\\\src\\\\selenium_mcp_server.py\"],\r\n \"env\": {\r\n \"PYTHONPATH\": \"C:\\\\path\\\\to\\\\selenium-mcp-server\\\\src\",\r\n \"PYTHONUNBUFFERED\": \"1\"\r\n }\r\n }\r\n }\r\n }\r\n ```\r\n- **macOS/Linux:**\r\n ```json\r\n {\r\n \"mcpServers\": {\r\n \"selenium\": {\r\n \"command\": \"python\",\r\n \"args\": [\"/path/to/selenium-mcp-server/src/selenium_mcp_server.py\"],\r\n \"env\": {\r\n \"PYTHONPATH\": \"/path/to/selenium-mcp-server/src\",\r\n \"PYTHONUNBUFFERED\": \"1\"\r\n }\r\n }\r\n }\r\n }\r\n ```\r\n\r\n### Option 3: Console Script\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"selenium\": {\r\n \"command\": \"selenium-mcp-server\"\r\n }\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udf10 Environment Variables\r\n- `PYTHONUNBUFFERED=1`: Ensures Python output is not buffered\r\n- `SELENIUM_LOG_LEVEL=INFO`: Sets logging level (DEBUG, INFO, WARNING, ERROR)\r\n- `PYTHONPATH`: Points to the directory containing the Python modules (needed for direct file execution)\r\n\r\n---\r\n\r\n## \ud83e\uddea Testing Your Configuration\r\nAfter configuring, test with:\r\n```json\r\n{\r\n \"name\": \"list_sessions\",\r\n \"arguments\": {}\r\n}\r\n```\r\nYou should get an empty list if no sessions are active.\r\n\r\n---\r\n\r\n## \u2753 FAQ / Troubleshooting\r\n\r\n**Q: I see \"0 tools enabled\" in Cursor AI.**\r\n- Make sure the package is installed: `pip install selenium-mcp-server` (or `pip install -e .` for development)\r\n- Verify the module works:\r\n ```bash\r\n python -c \"import selenium_mcp_server; print('Module found!')\"\r\n ```\r\n- Check if the entry point works:\r\n ```bash\r\n selenium-mcp-server --help\r\n ```\r\n- Try using the console script entry point in your config.\r\n\r\n**Q: \"Module not found\" errors**\r\n- Make sure you've installed the package: `pip install selenium-mcp-server` or `pip install -e .`\r\n- Check that the `PYTHONPATH` points to the correct directory if running from source\r\n- Verify the file paths are correct for your system\r\n\r\n**Q: \"Command not found\" errors**\r\n- Ensure Python is in your system PATH\r\n- Try using the full path to Python: `C:\\Python312\\python.exe` (Windows) or `/usr/bin/python3` (Linux/macOS)\r\n\r\n**Q: Permission errors**\r\n- On Windows, try running your MCP client as administrator\r\n- On Linux/macOS, check file permissions: `chmod +x src/selenium_mcp_server.py`\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful Model Context Protocol (MCP) server that brings Selenium WebDriver automation to AI assistants",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/krishnapollu/selenium-mcp-server/issues",
"Documentation": "https://github.com/krishnapollu/selenium-mcp-server#readme",
"Homepage": "https://github.com/krishnapollu/selenium-mcp-server",
"PyPI": "https://pypi.org/project/selenium-mcp-server/",
"Repository": "https://github.com/krishnapollu/selenium-mcp-server"
},
"split_keywords": [
"selenium",
" webdriver",
" automation",
" mcp",
" model-context-protocol",
" ai",
" assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ab1a1d5192a6ab6b1aff224163df1c9cc6552ad8c3b0ed25f0080afe1dbfff66",
"md5": "072a8f0dd1506b55bd5af2a369511ce2",
"sha256": "4a839a8b3857f602e623ae8ece81ad8d433258d2ad7fd189b9253cdf624b8e81"
},
"downloads": -1,
"filename": "selenium_mcp_server-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "072a8f0dd1506b55bd5af2a369511ce2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16170,
"upload_time": "2025-07-22T03:39:56",
"upload_time_iso_8601": "2025-07-22T03:39:56.417058Z",
"url": "https://files.pythonhosted.org/packages/ab/1a/1d5192a6ab6b1aff224163df1c9cc6552ad8c3b0ed25f0080afe1dbfff66/selenium_mcp_server-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e66a20883c139ef527e790fea3ed034d3856c23881e7ebd1c5f39c24926f7cd9",
"md5": "deacfc820ba98a30b116c2e3aed35c2a",
"sha256": "6c984103648214d77d0976eedcff30862f5093b0427596a35e44527b1db38294"
},
"downloads": -1,
"filename": "selenium_mcp_server-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "deacfc820ba98a30b116c2e3aed35c2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24374,
"upload_time": "2025-07-22T03:39:57",
"upload_time_iso_8601": "2025-07-22T03:39:57.599831Z",
"url": "https://files.pythonhosted.org/packages/e6/6a/20883c139ef527e790fea3ed034d3856c23881e7ebd1c5f39c24926f7cd9/selenium_mcp_server-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 03:39:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "krishnapollu",
"github_project": "selenium-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "selenium-mcp-server"
}
JSON
