Which integrations are available for this server?

Enables deployment and management of Selenium Grid browser instances in Docker containers, supporting Chrome, Firefox, and Edge browsers with configurable authentication and scaling options. Provides commands for deploying and uninstalling Selenium Grid in Kubernetes using Helm charts with configurable parameters. Provides support for deploying Selenium Grid in K3s lightweight Kubernetes environments for local development and testing of browser automation workflows. Enables deployment and management of Selenium Grid browser instances in Kubernetes clusters, with support for scalable browser automation through pod orchestration and Helm-based deployments. Provides a management interface for Selenium Grid browser instances, enabling creation and control of Chrome, Firefox, and Edge browsers for automation and testing workflows with VNC access support.

How do I use MCP Selenium Grid?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Selenium Grid launch a Chrome browser instance for testing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

🤖 MCP Selenium Grid

Tests GitHub Last Commit GitHub Release GitHub commits since latest release GitHub Commit Activity GitHub Contributors License

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

MCP Selenium Grid