{"id":30770369,"url":"https://github.com/fbettag/selenium-mcp","last_synced_at":"2026-04-13T18:01:39.667Z","repository":{"id":312725497,"uuid":"1048418196","full_name":"fbettag/selenium-mcp","owner":"fbettag","description":"Selenium Remote WebDriver MCP Server compatible with browserless. Docker/Kubernetes and uv ready.","archived":false,"fork":false,"pushed_at":"2025-09-01T17:01:05.000Z","size":30,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-13T02:41:56.371Z","etag":null,"topics":["mcp","mcp-server","mcp-servers","python3","selenium","selenium-webdriver","uvicorn"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fbettag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T12:14:23.000Z","updated_at":"2025-09-23T14:28:47.000Z","dependencies_parsed_at":"2025-09-01T17:26:45.574Z","dependency_job_id":"289699a6-e33b-4ff4-a002-59ef223a7740","html_url":"https://github.com/fbettag/selenium-mcp","commit_stats":null,"previous_names":["fbettag/selenium-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fbettag/selenium-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbettag%2Fselenium-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbettag%2Fselenium-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbettag%2Fselenium-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbettag%2Fselenium-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fbettag","download_url":"https://codeload.github.com/fbettag/selenium-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fbettag%2Fselenium-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31764317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","mcp-servers","python3","selenium","selenium-webdriver","uvicorn"],"created_at":"2025-09-04T23:04:14.048Z","updated_at":"2026-04-13T18:01:39.661Z","avatar_url":"https://github.com/fbettag.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Selenium MCP Server\n\nA Model Context Protocol (MCP) server that provides browser automation capabilities using Selenium WebDriver connected to a browserless service. This server runs without local browsers, connecting to browserless via TCP for scalable, containerized deployments.\n\n## Features\n\n- **Browser Automation**: Navigate to URLs, interact with elements, execute JavaScript\n- **Browserless Integration**: Connects to browserless service via WebDriver protocol\n- **Async Python**: Built with FastMCP for high-performance async operations\n- **Container Ready**: Alpine-based Docker image with no local browsers\n- **Session Management**: Automatic session handling per MCP context\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.13+\n- Browserless service running (local or remote)\n- UV package manager (recommended)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd selenium-mcp-server\n\n# Install with UV\nuv sync\n\n# Or with pip\npip install -e .\n```\n\n### Environment Setup\n\nSet the browserless service URL and optional authentication token:\n\n```bash\nexport BROWSERLESS_URL=http://localhost:3000  # Local browserless\nexport BROWSERLESS_URL=http://browserless:3000  # Kubernetes service\n\n# Optional: Set authentication token if browserless requires it\nexport BROWSERLESS_TOKEN=your-bearer-token-here\n```\n\n### Run the Server\n\n```bash\n# With UV\nuv run selenium-mcp\n\n# Or directly\npython -m selenium_mcp.server\n```\n\n## Claude Desktop Setup\n\nAdd to your Claude Desktop configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"selenium\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"selenium-mcp\"],\n      \"env\": {\n        \"BROWSERLESS_URL\": \"http://localhost:3000\",\n        \"BROWSERLESS_TOKEN\": \"your-bearer-token-here\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Navigate to URL\n```python\nnavigate_to_url({\n  \"url\": \"https://example.com\"\n})\n```\n\n### Find Element\n```python\nfind_element({\n  \"selector\": \".button-primary\",\n  \"by\": \"css\"  # css, xpath, id, name, class_name, tag_name, link_text, partial_link_text\n})\n```\n\n### Click Element\n```python\nclick_element({\n  \"selector\": \"#submit-button\",\n  \"by\": \"id\"\n})\n```\n\n### Execute JavaScript\n```python\nexecute_javascript({\n  \"script\": \"return document.title;\"\n})\n```\n\n### Take Screenshot\n```python\ntake_screenshot({})\n```\n\n### Get Page Info\n```python\nget_page_info({})\n```\n\n### Close Browser\n```python\nclose_browser({})\n```\n\n## Docker Deployment\n\n### Build the Image\n\n```bash\ndocker build -t selenium-mcp-server .\n```\n\n### Run with Docker Compose\n\n```yaml\nversion: '3.8'\nservices:\n  browserless:\n    image: browserless/chrome:latest\n    ports:\n      - \"3000:3000\"\n    environment:\n      - CONNECTION_TIMEOUT=60000\n      - MAX_CONCURRENT_SESSIONS=10\n\n  selenium-mcp:\n    image: selenium-mcp-server:latest\n    environment:\n      - BROWSERLESS_URL=http://browserless:3000\n      - BROWSERLESS_TOKEN=${BROWSERLESS_TOKEN:-}\n    ports:\n      - \"8000:8000\"\n    depends_on:\n      - browserless\n```\n\n### Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: selenium-mcp\nspec:\n  replicas: 2\n  selector:\n    matchLabels:\n      app: selenium-mcp\n  template:\n    metadata:\n      labels:\n        app: selenium-mcp\n    spec:\n      containers:\n      - name: selenium-mcp\n        image: selenium-mcp-server:latest\n        env:\n        - name: BROWSERLESS_URL\n          value: \"http://browserless-service:3000\"\n        - name: BROWSERLESS_TOKEN\n          valueFrom:\n            secretKeyRef:\n              name: browserless-secrets\n              key: token\n        ports:\n        - containerPort: 8000\n        resources:\n          requests:\n            memory: \"128Mi\"\n            cpu: \"100m\"\n          limits:\n            memory: \"256Mi\"\n            cpu: \"200m\"\n\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: browserless-service\nspec:\n  selector:\n    app: browserless\n  ports:\n  - port: 3000\n    targetPort: 3000\n```\n\n## Development\n\n### Virtual Environment\n\n```bash\n# Create virtual environment\nuv venv .venv\n\n# Activate on Unix/macOS\nsource .venv/bin/activate\n\n# Activate on Windows\n.venv\\\\Scripts\\\\activate\n\n# Install dependencies\nuv sync\n```\n\n### Testing\n\n```bash\n# Run tests\nuv run pytest\n\n# Start local browserless for testing\ndocker run -p 3000:3000 browserless/chrome:latest\n\n# Test the server\nBROWSERLESS_URL=http://localhost:3000 uv run selenium-mcp\n```\n\n### Linting and Formatting\n\n```bash\n# Format code\nuv run black src/\n\n# Lint code\nuv run ruff check src/\n\n# Type checking\nuv run mypy src/\n```\n\n## GitHub CI/CD Pipeline\n\nThe repository includes a GitHub Actions workflow that:\n\n1. **Tests**: Spins up browserless container and runs tests\n2. **Builds**: Creates Docker image with UV\n3. **Pushes**: Deploys to container registry on main branch\n\nSee `.github/workflows/ci.yml` for details.\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `BROWSERLESS_URL` | Browserless service URL | Required |\n| `BROWSERLESS_TOKEN` | Optional bearer token for browserless authentication | Empty |\n| `PYTHONPATH` | Python path for imports | `/app/src` |\n| `PYTHONUNBUFFERED` | Unbuffered Python output | `1` |\n\n## Browserless Configuration\n\nThis MCP server requires a browserless service. Recommended browserless configuration:\n\n```bash\ndocker run -p 3000:3000 \\\n  -e CONNECTION_TIMEOUT=60000 \\\n  -e MAX_CONCURRENT_SESSIONS=10 \\\n  -e DEFAULT_BLOCK_ADS=true \\\n  browserless/chrome:latest\n```\n\n## Performance Considerations\n\n- **Session Management**: Each MCP context gets its own browser session\n- **Connection Pooling**: Browserless handles multiple concurrent sessions\n- **Resource Limits**: Set appropriate memory/cpu limits in Kubernetes\n- **Timeouts**: Configure browserless timeouts based on use case\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection refused**: Ensure browserless is running and accessible\n2. **Authentication failed**: Check if `BROWSERLESS_TOKEN` is required and correctly set\n3. **Session timeout**: Increase browserless timeout settings\n4. **Element not found**: Use appropriate wait strategies in your scripts\n\n### Logs\n\nEnable debug logging by setting environment variables:\n\n```bash\nexport LOG_LEVEL=DEBUG\nexport BROWSERLESS_DEBUG=true\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes with tests\n4. Submit a pull request\n\n## Support\n\nFor issues and questions, please open a GitHub issue or check the browserless documentation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbettag%2Fselenium-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffbettag%2Fselenium-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffbettag%2Fselenium-mcp/lists"}