Camoufox MCP Server 🦊

An MCP (Model Context Protocol) server that provides browser automation capabilities using Camoufox - a privacy-focused Firefox fork with advanced anti-detection features.

Features

• 🛡️ Advanced Anti-Detection: Rotating OS fingerprints, realistic cursor movements, and browser fingerprint spoofing
• 🔧 Enhanced Parameters: Configurable wait strategies, timeouts, viewport dimensions, and more
• 🌐 Cross-Platform: Works on Windows, macOS, and Linux (including Docker)
• 📸 Screenshot Support: Capture page screenshots alongside HTML content
• 🚀 Easy Integration: Compatible with Claude Desktop, VS Code, Cursor, Windsurf, and more

Requirements

• Node.js 18 or higher (Node.js 20+ recommended for full camoufox CLI support)
• Python 3.x (for running tests)

Configuration for AI Assistants

<details> <summary>Claude Code (CLI)</summary>

Run the following command to add the Camoufox MCP server to Claude Code:

claude mcp add context7 -- npx -y camoufox-mcp-server

</details>

<details> <summary>Claude Desktop</summary>

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "camoufox": {
      "command": "npx",
      "args": ["camoufox-mcp-server"]
    }
  }
}

Using Docker

{
  "mcpServers": {
    "camoufox": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "followthewhit3rabbit/camoufox-mcp:latest"]
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "camoufox": {
      "command": "camoufox-mcp-server"
    }
  }
}

</details>

<details> <summary>VS Code (with Continue extension)</summary>

Add to your .continue/config.json:

{
  "models": [...],
  "mcpServers": {
    "camoufox": {
      "command": "npx",
      "args": ["camoufox-mcp-server"]
    }
  }
}

</details>

<details> <summary>Cursor</summary>

Add to your Cursor settings (Preferences → Features → MCP):

{
  "mcp": {
    "servers": {
      "camoufox": {
        "command": "npx",
        "args": ["camoufox-mcp-server"]
      }
    }
  }
}

</details>

<details> <summary>Windsurf</summary>

Add to your Windsurf configuration file at ~/.windsurf/mcp.json:

{
  "servers": {
    "camoufox": {
      "command": "npx",
      "args": ["camoufox-mcp-server"]
    }
  }
}

</details>

<details> <summary>Cline (VS Code Extension)</summary>

Add to VS Code settings.json:

{
  "cline.mcpServers": {
    "camoufox": {
      "command": "npx",
      "args": ["camoufox-mcp-server"]
    }
  }
}

</details>

Installation

Quick Start with npx

The easiest way to use Camoufox MCP Server is with npx (no installation required):

npx camoufox-mcp-server

Docker Installation

Run the server using Docker:

docker run -i --rm followthewhit3rabbit/camoufox-mcp:latest

NPM Installation

Install globally:

npm install -g camoufox-mcp-server

Or add to your project:

npm install camoufox-mcp-server

Usage

Once configured, the Camoufox MCP server provides a browse tool that your AI assistant can use to navigate websites and retrieve content.

Natural Language Triggers

The AI assistant will automatically use the browse tool when you use phrases like:

Basic Browsing:

• "Search for information about..."
• "Visit this website: ..."
• "Check what's on ..."
• "Navigate to ..."
• "Fetch content from ..."
• "Browse to ..."
• "Go to the website ..."
• "Open this page: ..."
• "Look at this URL: ..."
• "Scrape data from ..."

Privacy & Stealth:

• "Browse anonymously..."
• "Visit privately..."
• "Browse in stealth mode..."
• "Hide my IP while browsing..."
• "Browse through a proxy..."
• "Block tracking while visiting..."

Screenshots:

• "Take a screenshot of..."
• "Capture an image of..."
• "Show me visually what ... looks like"
• "I want to see how ... appears"

Performance:

• "Quick browse to..."
• "Fast loading of..."
• "Browse without images..."
• "Lightweight browsing to..."
• "Text-only content from..."

Basic Usage Examples

Can you check what's on example.com?

Search for information on the latest tech news from techcrunch.com

Visit github.com and tell me what's trending

The AI will automatically use the browse tool to navigate to websites and retrieve their HTML content.

Advanced Usage

Please visit example.com using a Windows browser with a 1920x1080 viewport and wait for all resources to load. Take a screenshot too.

More Conversational Examples

I need to research the current stock price of Apple. Can you go to finance.yahoo.com and search for AAPL?

Check if the restaurant's website has their menu online. Visit bistro-example.com and look for their menu section.

I'm looking for job postings in tech. Can you browse to linkedin.com/jobs and see what's available?

Navigate to the documentation site for React and find information about hooks.

The AI can use advanced parameters like:

• os: Spoof operating system (windows, macos, linux)
• waitStrategy: How to wait for page load (domcontentloaded, load, networkidle)
• timeout: Maximum time to wait (5-300 seconds)
• viewport: Custom browser dimensions
• screenshot: Capture a screenshot
• humanize: Enable realistic mouse movements
• locale: Set browser locale (e.g., 'en-US', 'fr-FR')
• block_webrtc: Block WebRTC for privacy
• proxy: Use a proxy server for requests
• enable_cache: Enable browser caching
• window: Set fixed window size

Example with Privacy Options

Browse example.com with WebRTC blocked and through a proxy server proxy.example.com:8080

Example with Custom Preferences

Visit example.com with a fixed 1280x720 window size and custom Firefox preferences to disable JavaScript

Example with Performance Optimization

Browse news.example.com with images blocked for faster loading and a 10 second timeout

Privacy & Stealth Examples

Browse example.com anonymously with maximum privacy and stealth mode

Visit sensitive-site.com through a proxy to hide my IP address

Browse privately to banking-site.com with WebRTC blocked and fingerprint protection

Access geo-blocked content via proxy server proxy.example.com:8080

Screenshot Examples

Take a screenshot of the homepage at example.com

Capture an image of how the login page looks on mobile-site.com

Show me visually what the product page looks like on store.example.com

Performance & Speed Examples

Quick browse to news-site.com without loading images for faster access

Lightweight browsing to documentation-site.com, text content only

Fast loading of search results from search-engine.com, no images needed

Advanced Privacy Combinations

Visit example.com with WebRTC blocked, WebGL blocked, images blocked, and geoip detection disabled

Browse anonymously through proxy 192.168.1.100:8080 with username 'user' and password 'pass' to access restricted content

Cross-Origin & Iframe Interaction

Browse iframe-test.example.com with Cross-Origin-Opener-Policy disabled to allow clicking elements in iframes

Access embedded content on complex-site.com and interact with all iframe elements

Tool Parameters

The browse tool accepts the following parameters:

Parameter	Type	Default	Description
url	string	required	The URL to navigate to
os	enum	random	Operating system to spoof: 'windows', 'macos', or 'linux'
waitStrategy	enum	'domcontentloaded'	Wait strategy: 'domcontentloaded', 'load', or 'networkidle'
timeout	number	60000	Page load timeout in milliseconds (5000-300000)
humanize	boolean	true	Enable realistic cursor movements
locale	string	system default	Browser locale (e.g., 'en-US')
viewport	object	{width: 1920, height: 1080}	Browser viewport dimensions
screenshot	boolean	false	Capture a screenshot of the page (triggers: "screenshot", "image", "capture", "show visually")
block_webrtc	boolean	true	Block WebRTC entirely for enhanced privacy (triggers: "private", "stealth", "hide IP")
proxy	string/object	none	Proxy configuration (triggers: "through proxy", "anonymously", "hide IP", "via proxy")
enable_cache	boolean	false	Cache pages and requests (uses more memory)
firefox_user_prefs	object	none	Custom Firefox user preferences
exclude_addons	array	none	List of default addons to exclude
window	array	random	Fixed window size [width, height] instead of random
args	array	none	Additional browser command-line arguments
block_images	boolean	false	Block all images for faster loading (triggers: "fast", "quick", "no images", "text only")
block_webgl	boolean	false	Block WebGL to prevent fingerprinting (triggers: "maximum privacy", "block tracking")
disable_coop	boolean	false	Disable Cross-Origin-Opener-Policy for iframe interaction (triggers: "iframe", "embedded content")
geoip	boolean	true	Auto-detect geolocation based on IP address
headless	boolean	auto	Run in headless mode (auto-detects best mode if not set)

Development

Building from Source

# Clone the repository
git clone https://github.com/whit3rabbit/camoufox-mcp.git
cd camoufox-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run locally
npm start

Running Tests

# Run test suite
npm test

# Run with local server
python3 tests/test_client.py --mode local

Docker Build

# Build and publish multi-architecture image
./publish_docker.sh

# Build for specific architecture
docker build -t camoufox-mcp .

Troubleshooting

Common Issues

1. "Camoufox browser not found"

   • Run npx camoufox fetch to download the browser
   • For Docker, the browser is pre-installed

2. "Cannot find module"

   • Ensure you've run npm install or are using npx
   • For global install: npm install -g camoufox-mcp-server

3. "MCP server not responding"

   • Check that the server is properly configured in your AI assistant
   • Verify the command path is correct
   • Check logs for error messages

Debug Mode

To see detailed logs, run the server directly:

node dist/index.js

Privacy & Security

Camoufox MCP Server uses the Camoufox browser, which includes:

• Fingerprint spoofing to prevent tracking
• Built-in uBlock Origin for ad blocking
• WebGL and WebRTC spoofing
• Canvas fingerprint protection
• Timezone and locale spoofing

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Acknowledgments

• Camoufox - The privacy-focused browser engine
• Model Context Protocol - The MCP specification
• Anthropic - For creating the MCP standard

Support

For issues and feature requests, please use the GitHub Issues page.