free-web-search-mcp

A free web search MCP server powered by real browsers.

Features · Install · Configure · Tools · Contributing · License

Features

• MCP server exposing web_search, fetch_page, and setup_camoufox tools

• Multiple browser backends selectable at runtime:

  • camoufox — stealth Firefox (anti-detect), default when installed

  • chrome — Playwright Chromium via installed Google Chrome

  • msedge — Playwright Chromium via installed Microsoft Edge

  • chromium — Playwright bundled Chromium

  • firefox — Playwright Firefox

  • webkit — Playwright WebKit

• Auto-setup Camoufox — pip install + binary download on demand

• Multiple search engines: Google (default), Bing, DuckDuckGo

• Page content extraction (plain text) for deep-reading a result URL

• Humanized typing, configurable proxy, locale, headless mode

• Block detection with actionable hints (e.g. "retry with browser='camoufox'")

Related MCP server: CloakBrowser Search MCP

Install

# Default install (Playwright path)
pip install -e .

# With Camoufox (recommended for stealth)
pip install -e ".[camoufox]"
camoufox fetch

# Playwright browsers (only download the ones you'll use)
playwright install chromium        # for backend=chromium
playwright install firefox         # for backend=firefox
playwright install webkit          # for backend=webkit
# chrome / msedge backends use the already-installed system browser, no download needed.

Camoufox missing on first run? It is installed and downloaded automatically — no manual steps required.

Configure

cp .env.example .env
# edit .env

Run

# Direct
python -m free_web_search_mcp

# Via script entry point
free-web-search-mcp

Integrate

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "free-web-search": {
      "command": "python",
      "args": ["-m", "free_web_search_mcp"],
      "cwd": "<path-to-this-project>"
    }
  }
}

opencode — opencode.json (global or project)

{
  "mcp": {
    "free-web-search": {
      "type": "local",
      "command": ["python", "-m", "free_web_search_mcp"],
      "enabled": true,
      "environment": {
        "HEADLESS": "true",
        "HUMANIZE": "true",
        "DEFAULT_BROWSER": "camoufox"
      }
    }
  }
}

Tools

web_search(query, max_results=10, engine="google", browser="")

Search the web and return a list of {position, title, url, snippet}.

fetch_page(url, max_chars=20000, browser="")

Fetch a URL and extract its main content as plain text.

setup_camoufox(force=False)

Ensure the Camoufox stealth browser is installed and its binary is downloaded. Runs pip install camoufox and python -m camoufox fetch automatically if missing. No-op if already installed.

Contributing

Pull requests are welcome. Please open them against a feature branch (not main):

git checkout -b feature/your-feature
git push -u origin feature/your-feature

Then open a PR targeting main. Keep commits focused and titled in the imperative mood (e.g. "Add support for Yandex"). Run ruff check . before submitting.

License

MIT — see LICENSE.