# 🤖 MCP Selenium Grid
[](https://github.com/CatchNip/mcp-selenium-grid/actions/workflows/1_tests.yml)
[](https://github.com/CatchNip/mcp-selenium-grid/releases)
[](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](https://github.com/astral-sh/uv) (Python dependency manager)
- [Docker](https://www.docker.com/) (for Docker deployment mode)
- [K3s](https://k3s.io/) (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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) 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:
```bash
uv run mcp-selenium-grid clean
```
```bash
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.
```json
{
"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>)
```bash
# 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:
```bash
# 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:
```bash
uvx mcp-selenium-grid helm --help
uvx mcp-selenium-grid helm deploy --help
uvx mcp-selenium-grid helm uninstall --help
```
Deploy using default parameters:
```bash
uvx mcp-selenium-grid helm deploy
```
Uninstall using default parameters:
```bash
# using default parameters
uvx mcp-selenium-grid helm uninstall --delete-namespace
```
```json
{
"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"
}
}
}
}
```
```json
{
"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
```bash
uvx mcp-selenium-grid server run
```
Custom args
```bash
API_TOKEN=CHANGE_ME uvx mcp-selenium-grid server run --host 127.0.0.1 --port 8000
```
#### Docker
Default args
```bash
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
```bash
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)
```json
{
"mcpServers": {
"mcp-selenium-grid": {
"url": "http://localhost:8000",
"headers": {
"Authorization": "Bearer CHANGE_ME"
}
}
}
}
```
```json
{
"mcpServers": {
"mcp-selenium-grid": {
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer CHANGE_ME"
}
}
}
}
```
```json
{
"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](CONTRIBUTING.md).
## 📄 License
MIT
