web-search-plus-mcp

# 🔍 web-search-plus-mcp <p align="center"> <img src="docs/assets/web-search-plus-logo.png" alt="web search plus logo" width="180"> </p> [](https://pypi.org/project/web-search-plus-mcp/) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io/) [](./LICENSE) [](https://glama.ai/mcp/servers/robbyczgw-cla/web-search-plus-mcp) **Multi-provider web search and Parallel-aware URL extraction for MCP clients.** `web-search-plus-mcp` is the standalone MCP packaging of Web Search Plus. It gives Claude Desktop, Cursor, NanoBot, Hermes native MCP, and other MCP-compatible hosts the same provider family used by the Hermes/OpenClaw Web Search Plus tools. Version note: `web-search-plus-mcp` uses its own MCP package version (`0.16.0`) while tracking the Web Search Plus v2.8.1 engine family where applicable. The plugin package is versioned separately as `hermes-web-search-plus v2.8.x`; Hermes-only setup/fastpath commands are not exposed by the MCP server. ## ✨ Features - **14 search providers + auto-routing** — provider metadata, schemas, defaults, and guarded/auto behavior are generated from the shared Web Search Plus provider registry - **7 extract providers with private-target protection** — Tavily, Exa, Linkup, Parallel, Firecrawl, You.com, Keenable, Serper - **Routing v2.3 auto-routing** — registry-backed routing for multilingual/current, docs/API, arXiv, CVE/security, local/shopping, OSS discovery, and answer/synthesis queries - **Quality reports + doctor checks** — optional routing/result diagnostics plus compact offline health checks for configured providers/cache - **Research mode** — opt-in multi-provider search + top-source extraction with a time budget - **Onboarding CLI** — `status`, `list`, `setup`, and persistent routing `config` helpers for MCP env/config wiring - **Zero-install run** — `uvx web-search-plus-mcp` - **MCP-native** — stdio server exposing stable `web_search` and `web_extract` tools ## 🚀 Quick Start ```bash # Run the MCP server instantly with uvx uvx web-search-plus-mcp # Or install globally pip install web-search-plus-mcp web-search-plus-mcp ``` At least one provider credential is required for search. Extraction needs at least one extraction-capable provider key. ## 🧭 Easier onboarding Check configured providers: ```bash web-search-plus-mcp status ``` List providers or presets: ```bash web-search-plus-mcp list providers web-search-plus-mcp list presets ``` Write a starter `.env` template and print a canonical MCP stdio snippet: ```bash web-search-plus-mcp setup --preset starter ``` The recommended starter preset is **You.com + Serper + Linkup**. It gives a practical Routing v2 baseline for fast current search, Google-style discovery, and extraction workflows without wiring every provider on day one. `status` returns a non-zero exit code when no search provider is configured, which makes it usable as a config check in scripts. Persistent routing preferences live in `config.json` rather than `.env`: ```bash web-search-plus-mcp config show web-search-plus-mcp config set-default you # strict fixed-provider mode web-search-plus-mcp config set-routing on # restore Routing v2 auto-routing web-search-plus-mcp config set-priority you,serper,exa,firecrawl,tavily,linkup,parallel,brave,keenable web-search-plus-mcp config set-fallback serper web-search-plus-mcp config disable perplexity web-search-plus-mcp config enable perplexity web-search-plus-mcp config disable kilo-perplexity web-search-plus-mcp config set-threshold 0.45 web-search-plus-mcp config reset --yes ``` Use `--config-path /path/to/config.json` or `WEB_SEARCH_PLUS_CONFIG=/path/to/config.json` for isolated MCP host installs. Provider secrets stay in environment variables; routing behavior stays in `config.json`. Other presets: - `minimal` — You.com only - `lean` — You.com + Linkup - `starter` — You.com + Serper + Linkup - `all` — every supported provider env var ## ⚙️ MCP host config Canonical stdio snippet for Claude Desktop, Cursor, NanoBot, or Hermes native MCP: ```json { "mcpServers": { "web-search-plus": { "command": "uvx", "args": ["web-search-plus-mcp"], "env": { "YOU_API_KEY": "your_you_key", "SERPER_API_KEY": "your_serper_key", "LINKUP_API_KEY": "your_linkup_key" } } } } ``` Common places to paste this snippet: - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` - Claude Desktop Linux: `~/.config/Claude/claude_desktop_config.json` - Cursor: project/user MCP config using the same `mcpServers` shape - Hermes native MCP: `~/.hermes/config.yaml` under `mcp_servers` with equivalent command/env fields You can also place a `.env` file next to the package/project with the same variables. ## 🔎 Search Providers - **You.com** — fast Routing v2 core provider for current, multilingual, and answer-shaped snippets - **Serper** — Google-style facts, news, shopping, local queries - **Exa** — semantic discovery, GitHub/docs, arXiv/academic, and OSS discovery - **Firecrawl** — web search plus scrape-ready content - **Parallel** — explicit-only LLM-ready web search with long excerpts (`PARALLEL_API_KEY`, `auto_allow=false`) - **Tavily** — research and analysis - **Linkup** — source-backed grounding/citations - **Brave** — explicit-only independent web index by default (`BRAVE_API_KEY`, `auto_allow=false`) - **Perplexity** — explicit-only native Perplexity API synthesized answers (`PERPLEXITY_API_KEY`, `sonar-pro`, `auto_allow=false`) - **Kilo Perplexity** — explicit-only Perplexity via Kilo gateway (`KILOCODE_API_KEY`, `perplexity/sonar-pro`, `auto_allow=false`) - **SearXNG** — privacy-first self-hosted meta-search - **SerpBase** — explicit-only Google SERP API (`SERPBASE_API_KEY`, `auto_allow=false`) - **Querit** — explicit-only multilingual, real-time AI search (`QUERIT_API_KEY`, `auto_allow=false`) - **Keenable** — independent web index with search and extraction (`KEENABLE_API_KEY`, or opt-in keyless public tier; off by default) ## 📄 Extract Providers - **Tavily** — default first choice; fastest reliable extraction in the v2.1 benchmark - **Exa** — fast contents API, strong for docs/academic pages - **Linkup** — clean markdown and source-grounded fetches - **Parallel** — fast excerpt-rich docs fallback with optional full-content extraction - **Firecrawl** — robust scrape fallback, useful for JS-heavy/blocked pages - **You.com** — LLM-ready snippets/content where available - **Keenable** — lowest-priority keyed or explicitly opted-in public fallback ### Keenable keyless public access Keenable exposes authenticated endpoints via `KEENABLE_API_KEY`. It also has keyless `/public` endpoints, but those are **opt-in and disabled by default**. Without a key, Keenable is treated as unconfigured unless you explicitly enable public egress: ```json { "keenable": { "allow_public": true } } ``` or set: ```bash KEENABLE_ALLOW_PUBLIC=1 ``` Use an API key for private or production use. The public endpoint sends queries and fetched URLs to a shared unauthenticated service and stays the lowest-priority fallback. ### Private/internal extraction target guard `web_extract` blocks user-supplied target URLs that point at private or internal networks before any provider is called. This covers loopback, RFC1918, CGNAT/shared-address ranges, IPv6 local/mapped-private ranges, multicast, cloud metadata hosts, and hostnames resolving to private/internal IPs. Operator-configured provider endpoints are separate: local Firecrawl-compatible backends can still run on `127.0.0.1` through provider config. If you intentionally need to extract trusted intranet URLs, opt in explicitly: ```json { "extract": { "allow_private_urls": true } } ``` Leave this off for public/agent-controlled URL extraction. ### GroktoCrawl / local Firecrawl-compatible backends The Firecrawl provider can target a local Firecrawl-v2-compatible backend by overriding its search and scrape URLs in `config.json`. For example, a local [GroktoCrawl](https://github.com/groktopus/groktocrawl) instance listening on `127.0.0.1:8080` can be used without adding a separate provider: ```json { "firecrawl": { "api_url": "http://127.0.0.1:8080/v2/search", "scrape_url": "http://127.0.0.1:8080/v2/scrape" } } ``` Keep `FIRECRAWL_API_KEY` configured if your backend enforces bearer authentication; local development instances may ignore the header. This does not make GroktoCrawl the default and does not claim coverage for every Firecrawl endpoint. ## 🛠 MCP Tool Reference This MCP server exposes stable `web_search` and `web_extract` tools. The old beta `web_answer` tool was removed to match Web Search Plus v2.1+: use `web_search` for source discovery and let the MCP host synthesize from results when needed. The Hermes plugin exposes the same stable capability as `web_search_plus` and `web_extract_plus`; the names differ because MCP and Hermes use different tool surfaces. ### `web_search` Use for source discovery, current events, prices, weather, sports lineups, schedules, and whenever you want the raw search landscape first. Parameters: - `query` — required search query - `provider` — `auto`, `serper`, `brave`, `tavily`, `exa`, `linkup`, `firecrawl`, `parallel`, `perplexity`, `kilo-perplexity`, `you`, `searxng`, `serpbase`, `querit`, `keenable` - `count` — results to return, default `5`, max `20` - `depth` — Exa depth: `normal`, `deep`, `deep-reasoning` - `time_range` — `hour`, `day`, `week`, `month`, `year` - `include_domains` / `exclude_domains` — domain allow/deny lists - `mode` — `normal` or `research` - `quality_report` — include routing/result diagnostics - `research_time_budget` — best-effort wall-clock budget for research mode Example MCP arguments: ```json { "query": "latest AI hardware news", "provider": "auto", "count": 5, "quality_report": true } ``` ### `web_extract` Parameters: - `urls` — required list of URLs - `provider` — `auto`, `tavily`, `exa`, `linkup`, `parallel`, `firecrawl`, `you`, `keenable` - `format` — `markdown` or `html` - `include_images` — include image metadata when supported - `include_raw_html` — include raw HTML when supported - `render_js` — render JavaScript before extraction when supported Example MCP arguments: ```json { "urls": ["https://example.com"], "provider": "auto", "format": "markdown" } ``` ## 🧠 Routing v2 Examples - `東京 AI ニュース 今日` → You.com multilingual/current search - `arXiv 2024 LLM scaling laws` → Exa academic discovery - `CVE-2025 openssl advisory` → Serper security/current search - `best bookshelf speakers under 1000 EUR Austria` → Serper/Firecrawl shopping/local search - `open source alternatives to Linear` → Exa/Firecrawl OSS discovery - `summarize the tradeoffs of RAG vs fine-tuning` → You.com with synthesis hint metadata for the MCP host Guarded providers can still be called explicitly. To let one participate in `provider="auto"`, opt in: ```bash web-search-plus-mcp config set-auto-allow parallel on web-search-plus-mcp config set-auto-allow parallel off ``` ## Credits Built on the Web Search Plus routing engine and packaged as a standalone MCP server. ## License MIT © 2026 robbyczgw-cla