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.

Tips: avoid captcha & blocks

Search engines flag requests by IP reputation, not just browser fingerprint. Camoufox handles the fingerprint side, but the IP matters more than people expect.

Run locally when possible. A residential home IP is clean and almost never gets captchas. A VPS/datacenter IP is frequently flagged — even with Camoufox, Google may serve reCAPTCHA. Prefer running this server on your local machine (or home server) and pointing your MCP client at it.

If you must run on a VPS:

• Set HUMANIZE=true and keep requests spaced out (no rapid bursts).

• Use a residential proxy via PROXY_URL (http://user:pass@host:port). This is the single most effective fix for captcha on datacenter IPs.

• Fall back to engine="bing" or engine="duckduckgo" — they are generally more permissive than Google.

• Rotate locale / user-agent across calls.

Block detection is built in. When a search hits a captcha/consent page, the tool returns a clear error and suggests retrying with browser="camoufox" — so the caller can switch backend automatically.

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.