🔍 web-search-plus-mcp

Give your AI app better web search and clean page reading. web-search-plus-mcp works with Claude Desktop, Cursor, NanoBot, Hermes, and other MCP apps. It searches across the services you choose, returns the original sources, and can try another service when one fails.

web-search-plus-mcp 4.1.1 keeps DonSeTch 3.6.1 search results and page extraction, and forwards Exa highlights, Parallel result limits/domain filters, and Tavily recency. Existing MCP tools and setup stay the same. The matching Hermes plugin adds an optional native backend; this MCP package does not need or include that adapter. See the 4.1.1 release notes.

🚀 Quick Start

# Run it without installing anything
uvx web-search-plus-mcp

# Or install it normally
pip install web-search-plus-mcp
web-search-plus-mcp

Add at least one search provider. You can start with one and add more later.

✨ What it does

• 15 search providers — use one service or let Web Search Plus choose
• 9 page-reading providers — turn web pages into clean text
• Automatic fallback — try another provider when the first one fails
• Real sources — keep the links and text the result came from
• Research mode — search several providers for broader questions
• Optional details — see which provider ran and how the result was found
• Simple setup tools — check your config and create a starter setup
• Optional local search — connect a separately installed DonSeTch executable through the WSP provider adapter

Version 4.0.3 tests DonSeTch 3.2.1. Version 4.0.2 adds Parallel Search modes (default fast). Version 4.0.1 hardens DonSeTch process reuse and diagnostics. Version 4.0.0 removed the optional Hound provider and added the separately installed DonSeTch 2.1.0 stdio adapter. See the 4.0.0 release notes and DonSeTch guide for migration, licensing, and runtime boundaries.

🧭 Easier onboarding

Check configured providers:

web-search-plus-mcp status

List providers or presets:

web-search-plus-mcp list providers
web-search-plus-mcp list presets

Write a starter .env template and print a canonical MCP stdio snippet:

web-search-plus-mcp setup --preset starter

The recommended starter preset is You.com + Serper + Linkup. It gives a practical source-only baseline for fast current search, Google-style discovery, and extraction workflows without wiring every provider on day one.

🧩 Agent Plugins package

This repository also contains a portable Agent Plugins 1.0 package for clients that support the standard. The root plugin.json describes the plugin and mcp.json connects the MCP server through the published PyPI package.

The portable configuration uses uvx with an exact web-search-plus-mcp version pin. Install uv first, then load this repository as an Agent Plugin in a compatible client such as VS Code, Cursor, GitHub Copilot, ChatGPT/Codex, or Kiro. Provider credentials are deliberately not stored in the plugin manifest; provide the required environment variables through the client or process environment.

The Agent Plugins format defines packaging and loading, not a central marketplace. Client-specific discovery and distribution remain outside the portable package contract.

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:

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 auto-routing
web-search-plus-mcp config set-priority you,serper,exa,firecrawl,tavily,linkup,parallel,brave,keenable
web-search-plus-mcp config set-extract-priority serper,tavily,exa,linkup,parallel,firecrawl,you,keenable
web-search-plus-mcp config set-fallback serper
web-search-plus-mcp config disable parallel
web-search-plus-mcp config enable parallel
web-search-plus-mcp config set-auto-allow parallel on
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. Search and extraction priorities are independent. If an extraction priority lists only selected providers, the remaining extract-capable providers are appended in the public registry order.

Other presets:

• minimal — You.com only
• lean — You.com + Linkup
• starter — You.com + Serper + Linkup
• all — every supported provider env var

🤖 Grok Build plugin

This repository is also a Grok Build plugin. Grok reads .mcp.json (the same pinned uvx server as above), skills/web-search-plus/SKILL.md (when and how to use web_search and web_extract), and .grok-plugin/plugin.json (metadata).

Install directly from the repository:

grok plugin install robbyczgw-cla/web-search-plus-mcp

Or pick web-search-plus from the marketplace (/plugin inside Grok Build). uv must be installed; provider keys come from your environment, the plugin ships none. Check with grok mcp doctor.

⚙️ MCP host config

Canonical stdio snippet for Claude Desktop, Cursor, NanoBot, or Hermes native MCP:

{
  "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.

🔌 MCP protocol compatibility

The server uses MCP Python SDK v2 and keeps the stdio boundary dual-era compatible:

• modern clients negotiate the stateless MCP 2026-07-28 protocol through server/discover
• legacy handshake clients continue to negotiate MCP 2025-11-25

The package exposes stdio only; the specification's Streamable HTTP session removal, subscriptions, OAuth changes, tasks, and multi-round-trip requests do not alter the two-tool Web Search Plus surface. Both protocol paths are covered by real subprocess tests.

🔎 Search Providers

• You.com — fast source-result provider for current and multilingual search
• 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 — LLM-ready web search with long excerpts; joins automatic routing when a key is configured (PARALLEL_API_KEY)
• Tavily — research and analysis
• Linkup — source-backed grounding/citations
• Brave — explicit-only independent web index by default (BRAVE_API_KEY, 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)
• DonSeTch — explicit-only local Search/Fetch provider through a separately installed stdio executable (DONSETCH_BIN)
• Octen via Monid — explicit-only source-result web search with native recency and domain filters (MONID_API_KEY, auto_allow=false)
• TinyFish — explicit-only BYOK source-result search (TINYFISH_API_KEY, auto_allow=false)

Octen source search via Monid

The adapter executes Octen's /search endpoint through Monid's documented HTTP API for ranked links and highlights. It explicitly disables full-content retrieval and does not call Octen's answer or Broad Search APIs. Configure MONID_API_KEY from Monid, then select provider="octen"; automatic routing remains unchanged unless you deliberately enable auto_allow. Access and billing use Monid's prepaid wallet; see Monid for current pricing and terms.

TinyFish source search