🤖 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 (Http Transport) and /sse (Server Sent Events).

Note: All requests to the server root http://localhost:8000 will be redirected to either /mcp or /sse endpoints, depending on the request, but you can choose to use directly /mcp (Http Transport) or /sse (Server Sent Events) endpoints.

Known Issues & Limitations

• When you use STDIO transport with the --stdio flag, the MCP Servers do not shut down the same way they do in the terminal. To clean up resources and remove containers or pods, run:

  uv run mcp-selenium-grid clean
  

  uv run mcp-selenium-grid clean -d kubernetes
  

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",
        "--stdio",
      ],
      "env": {
        "AUTH_ENABLED": "false",
        "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",
        "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER": "true"
      }
    }
  }
}

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

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",
        "--stdio",
      ],
      "env": {
        "AUTH_ENABLED": "false",
        "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",
        "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--network=host",
        "-v", "/home/user/.kube/config-local-k3s:/.kube/config-local-k3s:ro", // path to your kubeconfig file
        "-e", "AUTH_ENABLED=false",
        "-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", // path to your kubeconfig file
        "-e", "KUBERNETES__USE_HOST_DOCKER_INTERNAL=true",
        "-e", "KUBERNETES__CONTEXT=k3s-selenium-grid",
        "-e", "KUBERNETES__NAMESPACE=selenium-grid-dev",
        "-e", "KUBERNETES__SELENIUM_GRID_SERVICE_NAME=selenium-grid",
        "-e", "FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER=true",
        "ghcr.io/catchnip/mcp-selenium-grid:latest"
      ]
    }
  }
}

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

Server with auth enabled

UVX

Using default args

uvx mcp-selenium-grid server run

Custom args

API_TOKEN=CHANGE_ME uvx mcp-selenium-grid server run --host 127.0.0.1 --port 8000

Docker

Default args

docker run -i --rm --init --network=host \
  -v ~/.kube/config-local-k3s:/kube/config-local-k3s:ro \
  -e KUBERNETES__KUBECONFIG=/kube/config-local-k3s \
  ghcr.io/catchnip/mcp-selenium-grid:latest

Custom args

docker run -i --rm --init \
  --network=host \
  -v ~/.kube/config-local-k3s:/kube/config-local-k3s:ro \
  -e API_TOKEN=CHANGE_ME \
  -e ALLOWED_ORIGINS='["http://127.0.0.1:8000"]' \
  -e DEPLOYMENT_MODE=kubernetes \
  -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 \
  --add-host=host.docker.inte.rnal:host-gateway \
  -e KUBERNETES__USE_HOST_DOCKER_INTERNAL=true \
  -e KUBERNETES__CONTEXT=k3s-selenium-grid \
  -e KUBERNETES__NAMESPACE=selenium-grid-dev \
  -e KUBERNETES__SELENIUM_GRID_SERVICE_NAME=selenium-grid \
  ghcr.io/catchnip/mcp-selenium-grid:latest

Note: All environment variables have default values.

MCP Server configuration (mcp.json)

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "url": "http://localhost:8000",
      "headers": {
        "Authorization": "Bearer CHANGE_ME"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer CHANGE_ME"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-selenium-grid": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer CHANGE_ME"
      }
    }
  }
}

🤝 Contributing

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

📄 License

MIT