<div align="center">

free-web-search-mcp

A free web search MCP server powered by real browsers.

Features · Install · Configure · Tools · Contributing · License

</div>

---

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'")

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

Env	Default	Description
SEARCH_ENGINE	google	Default search engine: google | bing | duckduckgo
MAX_RESULTS	10	Max results returned per search
DEFAULT_BROWSER	auto	camoufox if installed, else chrome. Override per-call via param
HEADLESS	true	Run browser headless
HUMANIZE	true	Humanized typing
LOCALE	en-US	Browser locale
PROXY_URL	empty	Optional proxy http://user:pass@host:port
MCP_LOG_LEVEL	INFO	DEBUG | INFO | WARNING | ERROR

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}.

Parameter	Type	Default	Description
query	str	required	Search query string
max_results	int	10	1-20
engine	str	google	google | bing | duckduckgo
browser	str	auto	camoufox | chrome | msedge | chromium | firefox | webkit

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

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

Parameter	Type	Default	Description
url	str	required	Page URL
max_chars	int	20000	1000-50000
browser	str	auto	Same options as web_search

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.

Parameter	Type	Default	Description
force	bool	False	Re-download the binary even if present

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.