@zhafron/mcp-web-search

MCP Web Search

MCP server: web search and URL content extraction. No API keys required.

Features

• search_web - Multi-provider web search with automatic fallback (DuckDuckGo, Bing, SearXNG)
• fetch_url - Extract content from URLs with semantic truncation

Providers

Provider	API Key Required	Description
DuckDuckGo	No	HTML scraping, fast and simple
Bing	No	Puppeteer-based search (requires Chrome)
SearXNG	No	Self-hosted meta-search, unlimited usage

Requirements

• Node.js 18+
• Chrome/Chromium (for Bing provider)

MCP Configuration

Claude Code

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@zhafron/mcp-web-search"]
    }
  }
}

OpenCode

{
  "mcp": {
    "web-search": {
      "type": "local",
      "command": ["npx", "@zhafron/mcp-web-search"]
    }
  }
}

With Custom Configuration

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@zhafron/mcp-web-search"],
      "env": {
        "DEFAULT_SEARCH_PROVIDER": "duckduckgo",
        "SEARXNG_URL": "http://localhost:8099"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
DEFAULT_SEARCH_PROVIDER	duckduckgo	Default search provider (duckduckgo, bing, searxng)
SEARXNG_URL	http://localhost:8099	SearXNG instance URL
HTTP_TIMEOUT	15000	Request timeout (ms)
MCP_COMPAT_MODE	unset	Set to legacy to simplify tools/list schemas for MCP clients with weak discovery parsers

Legacy Discovery Compatibility

If your MCP client fails during discovery on array-valued JSON Schema nodes such as enum or required, set:

export MCP_COMPAT_MODE=legacy

This keeps tool execution unchanged, but advertises a simplified tools/list schema that removes array-valued schema nodes from tool metadata.

Anti-Bot Detection

This package uses realistic, rotating user agents to minimize bot detection:

• Random user agents from real browsers (Chrome, Firefox, Safari, Edge)
• Always up-to-date browser versions
• Desktop device category for consistency
• Different user agent per request

Chrome Setup (for Bing Provider)

OS	Command
Ubuntu/Debian	sudo apt install chromium-browser
Fedora	sudo dnf install chromium
Arch	sudo pacman -S chromium
macOS	brew install --cask google-chrome

Custom path: export CHROME_PATH=/path/to/chrome

Tools

search_web

Input: { q: string, limit?: number, lang?: string, provider?: "duckduckgo"|"bing"|"searxng" }

Output: { items: Array<{ title, url, snippet?, source }>, providerUsed, fallbackUsed, triedProviders }

Automatic Fallback:

• If default provider fails, automatically tries other providers
• Fallback order: DuckDuckGo → SearXNG → Bing (or vice versa based on default)

fetch_url

Input: { url: string, mode?: "compact"|"standard"|"full", max_length?: number, format?: "markdown"|"text"|"html" }

Mode	Characters	Tokens
compact	~3000	~750
standard	~8000	~2000
full	unlimited	-

Output: { markdown?, text?, format, url, title?, truncated?, original_length? }

SearXNG Setup

SearXNG is a free, self-hosted meta-search engine. Quick setup with Docker:

mkdir -p ~/docker/searxng && echo 'use_default_settings: true
search:
  safe_search: 0
  formats:
    - html
    - json
server:
  secret_key: "your_secret_key_here"
  limiter: false
  image_proxy: true
outgoing:
  request_timeout: 10.0
  max_request_timeout: 15.0' > ~/docker/searxng/settings.yml && docker run -d --name searxng -p 8099:8080 -v ~/docker/searxng/settings.yml:/etc/searxng/settings.yml:ro searxng/searxng:latest

SSRF Protection

Blocks localhost, 127.0.0.1, ::1, .local domains.

Troubleshooting

Issue	Solution
Chrome not found	Install Chrome or set CHROME_PATH
SearXNG 403	Enable JSON API in settings.yml
Timeout	Increase HTTP_TIMEOUT
MCP discovery error: 'list' object has no attribute 'get'	Set MCP_COMPAT_MODE=legacy to enable simplified discovery schemas

License

MIT