ira-ai-automation/selenium-mcp

Selenium MCP Server

A scalable, extensible, open-source server for managing Selenium browser automation sessions, inspired by Playwright MCP. Designed for GenAI-driven web automation, supporting local and remote execution.

Features

• REST API for browser session management and automation commands
• Supports Chrome, Firefox, Edge (extensible)
• Local and remote (Selenium Grid) execution
• Extensible command set and plugin architecture
• OpenAPI documentation
• Docker-ready

Architecture

• FastAPI: API server
• Session Manager: Handles multiple browser sessions
• Browser Abstraction: Local/remote drivers
• Command Registry: Extensible automation commands

Quick Start

Prerequisites

• Python 3.8+
• Chrome/Firefox/Edge browsers installed (or remote Selenium Grid)
• Redis server (for persistent rate limiting)
• (Optional) Docker

Makefile Usage

1. Create a virtual environment and install pip-tools

make venv

2. Add your dependencies to requirements.in (example: fastapi, selenium, uvicorn, python-dotenv)

3. Generate requirements.txt from requirements.in

make requirements

4. Install dependencies

make install

5. Run the server

make run

6. Run tests

make test

7. Clean up environment and build/test residue

make clean

API Endpoints

• POST /sessions — Start a new browser session
• POST /sessions/{session_id}/commands — Run a command (navigate, click, type, etc.)
• DELETE /sessions/{session_id} — Close session
• GET /sessions — List active sessions
• GET /health — Health check

Docker

docker build -t selenium-mcp .
docker run -p 8000:8000 selenium-mcp

OpenAPI & Usage Examples

API Documentation

• Interactive API docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Example: Perform Action

POST /sessions/{session_id}/actions
{
  "type": "click",
  "selector": {"role": "button", "aria_label": "Submit"}
}

Example: Type by Label

POST /sessions/{session_id}/actions
{
  "type": "type",
  "selector": {"label": "Username"},
  "value": "myuser"
}

Example: Navigate

POST /sessions/{session_id}/actions
{
  "type": "navigate",
  "value": "https://example.com"
}

Example: Get Element by Semantic Selector

GET /sessions/{session_id}/element?role=button&aria_label=Submit

Response:

{
  "tag": "BUTTON",
  "id": "submitBtn",
  "name": null,
  "role": "button",
  "aria_label": "Submit",
  "text": "Submit",
  "children": []
}

Redis Setup

# Install Redis (macOS)
brew install redis
redis-server

# Or using Docker
docker run -d -p 6379:6379 redis:alpine

Environment Variables

export MCP_API_KEY="your-secure-api-key"
export REDIS_URL="redis://localhost:6379"  # Optional, defaults to localhost

Advanced Features

Persistent Rate Limiting

• Redis-based rate limiting with configurable windows and limits
• Quota information endpoint: GET /quota
• Automatic cleanup of expired rate limit data

Transaction Management

Create complex automation workflows with rollback support:

Create Transaction

POST /sessions/{session_id}/transactions
{
  "steps": [
    {
      "action": {
        "type": "navigate",
        "value": "https://example.com"
      }
    },
    {
      "action": {
        "type": "type",
        "selector": {"label": "Username"},
        "value": "testuser"
      },
      "condition": "document.querySelector('input[name=\"username\"]') !== null",
      "rollback_action": {
        "type": "click",
        "selector": {"role": "button", "aria_label": "Clear"}
      }
    }
  ]
}

Execute Transaction

POST /transactions/{transaction_id}/execute

Check Transaction Status

GET /transactions/{transaction_id}

Rollback Transaction

POST /transactions/{transaction_id}/rollback

Transaction Features

• Conditions: JavaScript conditions for conditional execution
• Rollback Actions: Automatic rollback on failure
• Status Tracking: Detailed status for each step
• Manual Rollback: Rollback committed transactions

License

MIT