Camoufox MCP

Browser automation server for AI agents — powered by Camoufox and the Model Context Protocol.

What is Camoufox MCP?

Camoufox MCP is a production-ready MCP server that exposes browser automation capabilities to AI agents. It wraps Camoufox (a privacy-focused Firefox fork built on Playwright) behind a clean, modular API designed for agent workflows.

It is not a thin Playwright wrapper.
It is a structured browser runtime with session management, profile isolation, a security layer, and an extraction engine — all accessible through MCP tools.

Related MCP server: CamoFox MCP

Features

• Session management — multiple independent browser sessions with unique IDs

• Profile system — persistent browser profiles with per-profile configuration

• Navigation — goto, back, forward, reload with proper wait strategies

• Interaction — click, type, press, scroll with semantic selector support

• Extraction — structured text, HTML, links, and metadata extraction

• Screenshots — full-page, viewport, or element-level screenshots

• JavaScript execution — sandboxed browser_eval tool

• Tab management — open, close, switch between tabs

• Download management — controlled file downloads with path safety

• Security layer — permission model and URL/path validation

• Structured logging — session-level traceability, plain-text and JSON modes

• Graceful shutdown — no orphaned browser processes

Architecture

AI Client
   │ MCP (stdio)
   ▼
Camoufox MCP Server
   ├── Tool Registry
   ├── BrowserManager  ──► Camoufox (AsyncCamoufox)
   ├── SessionManager
   ├── ExtractionEngine
   ├── DownloadManager
   └── Security / Permission Layer

Each MCP tool follows the pattern:

MCP Tool → Service → Manager → Camoufox Adapter → Browser

Installation

With uv (recommended)

git clone https://github.com/camoufox-mcp/camoufox-mcp
cd camoufox-mcp
uv sync

From PyPI (once published)

uv tool install camoufox-mcp

Quick Start

# 1. Copy and configure environment
cp .env.example .env

# 2. Start the MCP server
camoufox-mcp

# or with uv
uv run camoufox-mcp

MCP Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

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

Available Tools (Phase 1)

More tools are added in subsequent phases — see docs/tools.md.

Configuration

All settings are controlled via environment variables.
See .env.example and docs/configuration.md.

Development

# Install with dev dependencies
uv sync --extra dev

# Lint
uv run ruff check src/

# Format
uv run ruff format src/

# Tests
uv run pytest

Docker

docker build -t camoufox-mcp .
docker run --rm -i camoufox-mcp

See Dockerfile for configuration options.

Security

This project is designed for legitimate browser automation, testing, research, and accessibility workflows. See docs/security.md for the full security model.

Roadmap

• Phase 2: Navigation, tabs, session persistence

• Phase 3: Click, type, press, scroll, wait

• Phase 4: Extraction engine (text, HTML, links, structured data)

• Phase 5: Screenshots, downloads

• Phase 6: Security / permission layer

• Phase 7: Unit + integration tests

• Phase 8: Full documentation

• Phase 9: PyPI release, Docker image

License

MIT — see LICENSE.