Agent Web Search is an open-source, MIT-licensed web search MCP server, command-line tool, and Python library designed for AI agents. It is not a traditional meta-search aggregator like Google/Bing/Baidu: traditional aggregation distributes keywords to conventional engines and then merges result pages, whereas Agent Web Search aggregates search capabilities built for agents, including model-native web search, agent-oriented search APIs, and sources that can accept natural language questions and directly return answers, citations, or structured evidence. Among the current providers, only DDGS is a traditional search backend.
Purpose and positioning This project provides agents with a unified, neutral search contract, enabling them to obtain normalized results through the same MCP tool, CLI, or Python API, and some model backends can also return answers. It is suitable for agents that support shell or MCP, such as Claude Code, Hermes, DeepSeek Harness (DSH), OpenCode, and Codex CLI, as well as ordinary shell scripts, Python applications, and remote Streamable HTTP MCP clients.
Main capabilities Divided into three categories of search capabilities:
- Traditional search backend: DDGS, uses DuckDuckGo, requires no API key, and installs the ddgs dependency with the package.
- Model providers: use model-native search or web-connected surfaces, and can return model-generated answers with citations or explicit search evidence. Includes ARK, Gemini, Grok, DeepSeek, Responses, Messages, Zhipu Chat Search, and Codex Alpha.
- Agent search providers: designed for agent consumption, supporting natural language queries, structured source lines, high-signal excerpts, or metadata suitable for citation. Includes Exa, Parallel, Brave, Perplexity, Tavily, You.com, and Zhipu Web Search. Other features: providers can run concurrently, and a single provider failure will not discard other successful results; the default free, keyless providers are DDGS, Exa, and Parallel; no telemetry, no shared-key service, and keys are supplied through runtime environment variables; the provider architecture is open, allowing new search backends to be added without changing the MCP, Hermes, CLI, or Python interfaces.
Usagemethods Three integration forms: native MCP tool, native plugin (Hermes, DeepSeek Harness), or a CLI taught to agents through a standard Agent Skill. Requires Python 3.10+. Quick start:
- Try without installation: uvx --from agent-web-search-mcp agent-web-search "<question>".
- Recommended installation to the global user environment: pipx install agent-web-search-mcp, or python -m pip install agent-web-search-mcp. Two commands: agent-web-search is the search CLI; agent-web-search-mcp is the stdio and Streamable HTTP MCP server. Method 1 MCP: after installing the package, configure the MCP client to launch agent-web-search-mcp; if uvx is already available, you can use command uvx, args ["agent-web-search-mcp"] to run without a persistent installation. Remote deployment exposes an authenticated POST /mcp and a public GET /healthz; any public deployment must set AGENT_WEB_SEARCH_AUTH_TOKEN and it must be at least 32 characters; the server is stateless and does not create an MCP-Session-Id. Method 2 CLI + Agent Skill (recommended for agents with terminal execution capability): install with pipx install agent-web-search-mcp, install the bundled Skill via npx skills add JerryLiu369/agent-web-search --skill agent-web-search (if the skills installer is not supported, copy skills/agent-web-search to the client Skills directory), and then the agent can call the CLI to search. On success, the CLI writes one JSON document to stdout; if all providers fail, it writes the shared all_providers_failed JSON to stderr and exits with status code 1 Exit, to facilitate distinguishing real failures from empty results.
Requests and Responses MCP exposes a tool named web_search, and the CLI maps the same inputs. Provider selection has two levels: AGENT_WEB_SEARCH_PROVIDERS defines the set of providers at process startup; the request-level providers parameter can narrow that set, but cannot enable providers that were disabled at startup. Each successful provider result appears under providers, and failures are omitted; if all fail, a tool error is returned, using the stable code all_providers_failed and including diagnostics for each provider. The CLI, MCP server, and Hermes plugin are all thin wrappers around agent_web_search.SearchEngine, and SearchRequest accepts the same fields as the MCP tool parameters.
Key Provider Configuration Points Configuration is read from environment variables, and the process must be restarted after changes. DDGS requires no key. Exa supports paid and keyless modes, and when EXA_API_KEY is absent it falls back to the free MCP endpoint on a best-effort basis. Parallel returns information-dense excerpts oriented toward LLM context; without a key it uses the free Search MCP, and with PARALLEL_API_KEY it uses the paid Search REST API; it is enabled by default and the key is optional. ARK uses the Responses API's model web search and can be configured with multiple models in rotation and multiple keys. Brave, Tavily, Perplexity, You.com, Zhipu Web Search, Zhipu Chat Search, Gemini, Grok, DeepSeek, Codex Alpha, and others all need to be added to AGENT_WEB_SEARCH_PROVIDERS after providing a key. After Grok is enabled, the tool mode adds grok_search_mode (web_search, x_search, both). DeepSeek uses the official Anthropic-compatible Messages API and the native web_search_20250305 server tool. Perplexity uses the native structured Search API, returning result rows rather than Sonar prose answers. You.com merges web pages and news and deduplicates by max_results. Zhipu Web Search and Zhipu Chat Search are two independent providers, with no API/Chat fallback.
Limitations and Notes API keys must not be placed in shell history, source code, Git commits, screenshots, or checked-in MCP configuration; they should be provided through server-side or local environment variables. Each provider's quotas, supported models, validity periods, and data licensing terms may change, so the official terms should be consulted. DDGS is the only traditional search backend. Remote deployments must set an authentication token. Some providers may return valid responses that have answers but empty result lists. Details and other provider configurations not listed here are not fully provided in the materials; please refer to the project repository and the .env.example template.
