Falamarcao/mcp-selenium-grid

🤖 MCP Selenium Grid

A Model Context Protocol (MCP) server for managing Selenium browser instances through a REST API. Useful for browser automation and testing workflows.

The MCP Selenium Grid provides a REST API 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 other Selenium-compatible browsers
• 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

📖 Usage

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

Configuration

The server uses config.yaml for configuration settings including:

• API tokens and authentication
• Deployment mode (Docker/Kubernetes)
• Browser configurations and resource limits
• Kubernetes context and namespace settings

MCP Client Configuration

To use the MCP Selenium Grid with MCP-compatible clients (like Cursor, VS Code, etc.), add the server configuration to your mcp.json file:

{
  "mcpServers": {
    "selenium-grid": {
      "command": "uv",
      "args": ["run", "fastapi", "run", "src/app/main.py"],
      "env": {
        "API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Once the server is running, you can access the interactive API documentation at: http://localhost:8000/docs

🚀 Quick Start for Development

1. Prerequisites

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

2. Setup

# Clone the repository
 git clone <this-repo-url>
 cd <repo>

# Create a virtual environment and install dev/test dependencies
 uv venv
 uv sync --all-groups --extra test

3. Kubernetes Setup (Optional)

This project requires a Kubernetes cluster for running tests and managing browser instances. 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

Using kubernetes context name from :

uv run helm-selenium-grid deploy

For a given kubernetes context name:

uv run helm-selenium-grid deploy --context k3s-selenium-grid

Uninstall:

uv run helm-selenium-grid uninstall --delete-namespace
uv run helm-selenium-grid uninstall --context k3s-selenium-grid --delete-namespace

See for more details.

4. Start Server

uv run fastapi dev src/app/main.py

uv run uses the virtual environment automatically. Activating the environment is optional but helps IDEs.

5. Running Tests

uv run pytest -m unit         # Unit tests
uv run pytest -m integration  # Integration tests (needs Docker/K8s)
uv run pytest -m e2e          # E2E tests (needs Docker/K8s)

🧪 CI & Workflow Testing

• To test GitHub Actions workflows locally, see for simple act usage instructions.

  See for test details.

6. Code Quality

uv run ruff check .           # Lint
uv run mypy .                 # Type check
uv run ruff format .          # Format

This project uses pre-commit hooks configured in .pre-commit-config.yaml for automated code quality checks. If the pre-commit configuration is updated, run:

uv run pre-commit install && uv run pre-commit autoupdate && uv run pre-commit run --all-files

Installs hooks, updates them to latest versions, and runs all hooks on all files.

7. Clean Cache

uvx pyclean .                 # Clear pycache
uv run ruff clean             # Clear ruff cache

📦 Dependency Management

• Install all dependencies: uv sync --all-groups --extra test
• Add a dependency: uv add <package>
• Add a dev dependency: uv add <package> --dev
• Add a test dependency: uv add <package> --optional test

📄 License

MIT