README.md

🤖 MCP Selenium Grid

A Model Context Protocol (MCP) server for managing Selenium Grid browser instances. Useful for browser automation and testing workflows.

The MCP Selenium Grid provides a MCP Server for creating and managing browser instances in both Docker and Kubernetes environments. It's designed to work with AI agents and automation tools that need browser automation capabilities.

Key Features

• Multi-browser support: Chrome, Firefox and Edge
• Dual backend support: Docker and Kubernetes deployment modes
• Secure API: Token-based authentication for browser management
• Scalable architecture: Support for multiple browser instances
• MCP compliance: Follows Model Context Protocol standards

🚀 Quick Start

Prerequisites

• uv (Python dependency manager)
• Docker (for Docker deployment mode)
• K3s (for Kubernetes deployment mode, optional)

📖 Usage

The MCP Selenium Grid provides a Web API for creating and managing browser instances. The server runs on localhost:8000 and exposes MCP endpoints at /mcp.

MCP Client Configuration

🐳 Docker Deployment

For Docker-based deployment, ensure Docker is running and use the Docker configuration in your MCP client setup.

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "command": "uvx",
      "args": ["mcp-selenium-grid", "server", "run",
        "--host", "127.0.0.1",
        "--port", "8000"
      ],
      "env": {
        "API_TOKEN": "CHANGE_ME",
        "ALLOWED_ORIGINS": "[\"http://127.0.0.1:8000\"]",
        "DEPLOYMENT_MODE": "docker",
        "SELENIUM_GRID__USERNAME": "USER",
        "SELENIUM_GRID__PASSWORD": "CHANGE_ME",
        "SELENIUM_GRID__VNC_PASSWORD": "CHANGE_ME",
        "SELENIUM_GRID__VNC_VIEW_ONLY": "false",
        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": "4",
        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": "1"
      }
    }
  }
}

The server will be available at http://localhost:8000 with interactive API documentation at http://localhost:8000/docs.

☸️ Kubernetes Deployment

3. Kubernetes Setup (Optional)

This project supports Kubernetes deployment for scalable browser instance management. We use K3s for local development and testing.

Install K3s (https://docs.k3s.io/quick-start)

# Install K3s
curl -sfL https://get.k3s.io | sh -

# Verify installation
k3s --version

# Start if not running
sudo systemctl start k3s

Create K3s Kubernetes Context (Optional)

After installing K3s, you might want to create a dedicated kubectl context for it:

# Copy K3s kubeconfig
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config-local-k3s
sudo chown $USER:$USER ~/.kube/config-local-k3s
chmod 600 ~/.kube/config-local-k3s

# Create context
KUBECONFIG=~/.kube/config-local-k3s \
kubectl config set-context k3s-selenium-grid \
  --cluster=default \
  --user=default

Deploy Selenium Grid

Please run for help to get to know the available commands and parameters:

uvx mcp-selenium-grid helm --help
uvx mcp-selenium-grid helm deploy --help
uvx mcp-selenium-grid helm uninstall --help

Deploy using default parameters:

uvx mcp-selenium-grid helm deploy

Uninstall using default parameters:

# using default parameters
uvx mcp-selenium-grid helm uninstall --delete-namespace

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "command": "uvx",
      "args": ["mcp-selenium-grid", "server", "run",
        "--host", "127.0.0.1",
        "--port", "8000"
      ],
      "env": {
        "API_TOKEN": "CHANGE_ME",
        "ALLOWED_ORIGINS": "[\"http://127.0.0.1:8000\"]",
        "DEPLOYMENT_MODE": "kubernetes",
        "SELENIUM_GRID__USERNAME": "USER",
        "SELENIUM_GRID__PASSWORD": "CHANGE_ME",
        "SELENIUM_GRID__VNC_PASSWORD": "CHANGE_ME",
        "SELENIUM_GRID__VNC_VIEW_ONLY": "false",
        "SELENIUM_GRID__MAX_BROWSER_INSTANCES": "4",
        "SELENIUM_GRID__SE_NODE_MAX_SESSIONS": "1",
        "KUBERNETES__KUBECONFIG": "~/.kube/config-local-k3s",
        "KUBERNETES__CONTEXT": "k3s-selenium-grid",
        "KUBERNETES__NAMESPACE": "selenium-grid-dev",
        "KUBERNETES__SELENIUM_GRID_SERVICE_NAME": "selenium-grid"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-p", "8000:80",
        "-e", "API_TOKEN=CHANGE_ME",
        "-e", "ALLOWED_ORIGINS=[\"http://127.0.0.1:8000\"]",
        "-e", "DEPLOYMENT_MODE=kubernetes", // required for docker
        "-e", "SELENIUM_GRID__USERNAME=USER",
        "-e", "SELENIUM_GRID__PASSWORD=CHANGE_ME",
        "-e", "SELENIUM_GRID__VNC_PASSWORD=CHANGE_ME",
        "-e", "SELENIUM_GRID__VNC_VIEW_ONLY=false",
        "-e", "SELENIUM_GRID__MAX_BROWSER_INSTANCES=4",
        "-e", "SELENIUM_GRID__SE_NODE_MAX_SESSIONS=1",
        "-e", "KUBERNETES__KUBECONFIG=/kube/config-local-k3s",
        "-e", "KUBERNETES__CONTEXT=k3s-selenium-grid",
        "-e", "KUBERNETES__NAMESPACE=selenium-grid-dev",
        "-e", "KUBERNETES__SELENIUM_GRID_SERVICE_NAME=selenium-grid",
        "ghcr.io/falamarcao/mcp-selenium-grid:latest"
      ]
    }
  }
}

The server will be available at http://localhost:8000 with interactive API documentation at http://localhost:8000/docs.

🤝 Contributing

For development setup, testing, and contribution guidelines, please see CONTRIBUTING.md.

📄 License

MIT