# Camoufox MCP Server

# Deprecated: moved to `camoufox-browser`
This repository is deprecated.
The project has moved to:

- Repository: https://github.com/rlgrpe/camoufox-browser-cli
- PyPI: https://pypi.org/project/camoufox-browser/

A Python MCP (Model Context Protocol) server providing full browser automation with [Camoufox](https://github.com/daijro/camoufox) anti-detection capabilities.

## Features

- **21 browser automation tools** for complete browser control
- **Anti-detection**: Automatic fingerprint randomization to avoid bot detection
- **Lazy initialization**: Browser only launches on first tool call
- **Persistent sessions**: Browser persists between tool calls
- **Tab management**: Support for multiple tabs/pages
- **Form automation**: Fill forms, upload files, handle dialogs

## Installation

### Quick Start (uvx - recommended)

```bash
uvx camoufox-mcp
```

### Using pipx

```bash
pipx run camoufox-mcp
```

### Using pip

```bash
pip install camoufox-mcp
camoufox-mcp
```

### From source

```bash
# Clone the repository
git clone https://github.com/rlgrpe/camoufox-mcp-python.git
cd camoufox-mcp-python

# Install with uv
uv sync
```

### Install Camoufox browser

After installing the package, you need to download the Camoufox browser binary. **The command depends on how you installed the package:**

#### If installed via uvx (recommended)

```bash
uvx camoufox fetch
```

#### If installed via pipx

```bash
pipx run camoufox fetch
```

#### If installed via pip

```bash
# macOS
python3 -m camoufox fetch

# Linux
python -m camoufox fetch

# Windows
camoufox fetch
```

#### If installed from source (uv)

```bash
uv run python -m camoufox fetch
```

#### Linux system dependencies

On Linux, you also need to install system dependencies:

```bash
# Ubuntu/Debian
sudo apt install -y libgtk-3-0 libx11-xcb1 libasound2

# Arch
sudo pacman -S gtk3 libx11 libxcb cairo libasound alsa-lib
```

#### To uninstall the browser binary

```bash
# Use the same method as installation:
uvx camoufox remove          # if using uvx
pipx run camoufox remove     # if using pipx
camoufox remove              # if using pip
uv run python -m camoufox remove  # if using uv from source
```

## Usage

### Start the server

```bash
# Using uvx (recommended)
uvx camoufox-mcp

# Using uv (from source)
uv run camoufox-mcp

# Or as a module
python -m camoufox_mcp
```

### Add to Claude Code

```bash
claude mcp add camoufox-mcp -- uvx camoufox-mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uvx",
      "args": ["camoufox-mcp"]
    }
  }
}
```

Or if running from source:

```json
{
  "mcpServers": {
    "camoufox-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/camoufox-mcp-python",
        "camoufox-mcp"
      ]
    }
  }
}
```

## Tools Reference

### Navigation (4 tools)

| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_navigate_back` | Go back to the previous page |
| `browser_snapshot` | Capture accessibility snapshot of the current page |
| `browser_wait_for` | Wait for text to appear/disappear or a specified time |

### Interaction (6 tools)

| Tool | Description |
|------|-------------|
| `browser_click` | Click on an element |
| `browser_type` | Type text into an element |
| `browser_hover` | Hover over an element |
| `browser_drag` | Drag and drop between two elements |
| `browser_press_key` | Press a key on the keyboard |
| `browser_select_option` | Select an option in a dropdown |

### Page (4 tools)

| Tool | Description |
|------|-------------|
| `browser_evaluate` | Evaluate JavaScript on the page or element |
| `browser_console_messages` | Get console messages |
| `browser_network_requests` | Get network requests |
| `browser_take_screenshot` | Take a screenshot |

### Forms (3 tools)

| Tool | Description |
|------|-------------|
| `browser_fill_form` | Fill multiple form fields |
| `browser_file_upload` | Upload files |
| `browser_handle_dialog` | Handle dialogs (alert, confirm, prompt) |

### Session (4 tools)

| Tool | Description |
|------|-------------|
| `browser_tabs` | List, create, close, or select tabs |
| `browser_resize` | Resize the browser window |
| `browser_close` | Close the browser |
| `browser_install` | Install Camoufox browser |

## Configuration

The browser can be configured via the `BrowserConfig` class in `camoufox_mcp/config.py`. Available options:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `os` | str | None | OS to spoof (windows/macos/linux) |
| `headless` | bool/str | False | Headless mode (or 'virtual') |
| `humanize` | bool/float | True | Human-like cursor movements |
| `geoip` | bool | True | Auto-detect geolocation from IP |
| `proxy` | str/dict | None | Proxy configuration |
| `block_webrtc` | bool | True | Block WebRTC leaks |
| `block_webgl` | bool | False | Block WebGL fingerprinting |
| `block_images` | bool | False | Block image loading |
| `locale` | str | None | Browser locale |
| `viewport` | dict | None | Viewport dimensions |
| `enable_cache` | bool | True | Enable caching |
| `timeout` | int | 30000 | Page load timeout (ms) |
| `wait_strategy` | str | "domcontentloaded" | Wait strategy |
| `ublock` | bool | False | Enable uBlock Origin |

### Proxy Configuration Example

```python
proxy = {
    'server': 'http://proxy.example.com:8080',
    'username': 'user',
    'password': 'pass'
}
```

## Development

```bash
# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Format code
uv run ruff format

# Lint
uv run ruff check
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Related Projects

- [Camoufox](https://github.com/daijro/camoufox) - The anti-detect browser this MCP server is built on
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol specification
- [FastMCP](https://github.com/jlowin/fastmcp) - Python framework for building MCP servers