<div align="center">

Agent Web Search

<!-- mcp-name: io.github.JerryLiu369/agent-web-search -->

Agent-native web search — model-native grounding and agent search APIs behind one provider-neutral contract.

English | 简体中文

<p><strong>One-click remote MCP</strong></p> <p> <a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FJerryLiu369%2Fagent-web-search&amp;env=AGENT_WEB_SEARCH_AUTH_TOKEN"><img alt="Deploy with Vercel" src="https://vercel.com/button" height="34"></a> <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2FJerryLiu369%2Fagent-web-search&amp;envs=AGENT_WEB_SEARCH_AUTH_TOKEN"><img alt="Deploy on Railway" src="https://railway.com/button.svg" height="34"></a> <a href="https://render.com/deploy?repo=https://github.com/JerryLiu369/agent-web-search"><img alt="Deploy to Render" src="https://render.com/images/deploy-to-render-button.svg" height="34"></a> <a href="https://zeabur.com/templates/8MQZG0?referralCode=JerryLiu369"><img alt="Deploy on Zeabur" src="https://zeabur.com/button.svg" height="34"></a> </p>

Works with Codex CLI, Claude Code, OpenCode, Hermes, DeepSeek Harness (DSH), ordinary shell scripts, Python applications, and remote Streamable HTTP MCP clients.

Quickstart · Use with an agent · Providers · Configuration <br> Shared interface · Other interfaces · Troubleshooting · FAQ · Architecture · Development

</div>

---

Agent Web Search (PyPI: agent-web-search-mcp) is an open-source, MIT-licensed web search MCP server, CLI, and Python library for AI agents. It gives an agent three ways to reach the same provider-neutral search core: a native MCP tool, a native plugin (Hermes, DeepSeek Harness), or a CLI taught through a standard Agent Skill.

If you are an AI agent: install with pipx install agent-web-search-mcp (or try instantly with uvx --from agent-web-search-mcp agent-web-search "<question>"), then read skills/agent-web-search/SKILL.md — it teaches the CLI pathway only (for MCP setups, follow Option 1 instead). llms.txt is the machine-readable doc index.

This is not a Google/Bing/Baidu metasearch wrapper. Traditional search aggregation fans a keyword query out to conventional engines and merges their result pages. Agent Web Search instead aggregates search capabilities built for agents: model-native web grounding, agent-oriented search APIs, and context-ready sources that accept natural-language questions and return answers, citations, or structured evidence in forms an agent can use directly. DDGS is the only conventional search backend in the current provider set.

          Natural-language question
                      |
                      v
                 SearchEngine
          +-----------+-----------+
          |           |           |
          v           v           v
        DDGS        Model       Agent
                  grounding     APIs
                 (Responses,   (Exa,
                  ARK, Grok,    Parallel,
                  Gemini...)    Tavily...)

Installation & Quickstart

Three steps, about a minute: try it instantly, install it once, then connect your agent. Requirements: Python 3.10+. Default providers (DDGS, Exa, Parallel) require no API key.

Try without installing

Test immediate search capabilities using uvx (no environment modification):

# Direct natural-language search with keyless defaults
uvx --from agent-web-search-mcp agent-web-search "What changed in the latest OpenAI Codex CLI?"

# Inspect MCP server arguments
uvx agent-web-search-mcp --help

Install

Install once into your global user environment (recommended):

# Recommended isolated installation
pipx install agent-web-search-mcp

# Or install into the active Python environment
python -m pip install agent-web-search-mcp

Verify

# 1. Verify the CLI and run a real search
agent-web-search --version
agent-web-search "What changed in the latest OpenAI Codex CLI?"

# 2. Verify the MCP server binary
agent-web-search-mcp --help

Two commands, two roles:

• agent-web-search: Direct search CLI for terminals, shell scripts, and Agent Skills.
• agent-web-search-mcp: Stdio and Streamable HTTP MCP server for MCP clients.

Pick your agent integration

| Integration | Client / Environment | Setup | | :--- | :--- | :--- | | CLI + Skill (Recommended) | Terminal agents (Claude Code, Codex, OpenCode, Hermes) | npx skills add JerryLiu369/agent-web-search --skill agent-web-search (Details) | | MCP (Stdio) | Codex CLI, Claude Code, Cursor, Cline, Roo Code | codex mcp add agent-web-search -- agent-web-search-mcp (Details) | | DSH Plugin | DeepSeek Harness (desktop & web) | dsh plugin --profile desktop add github:JerryLiu369/agent-web-search (Details) | | Hermes Plugin | Hermes Agent | hermes plugins install JerryLiu369/agent-web-search (Details) |

[!TIP] Why CLI + Skill is recommended for shell-capable agents: If your agent already has terminal/bash execution capabilities (like Claude Code, Codex CLI, OpenCode, or Hermes), the CLI + Skill pathway offers the lowest friction and highest reliability. No MCP JSON configuration to debug, no background transport lifecycle to manage, and clean stdout JSON output taught through a standard Skill.

Why Agent Web Search

Traditional search aggregation (Google/Bing/Baidu wrappers, scraped SERPs) sends a keyword query to conventional engines and merges result pages. Agent Web Search instead aggregates search capabilities built for agents: one tool call returns structured, citation-ready evidence — or, through model-native grounding providers, a synthesized answer with explicit citations. A measured benchmark shows the practical difference: on a natural-language Chinese query asking for official sources, conventional SERP backends returned no government-domain results in the top 5, while the grounding provider returned official figures from China's General Administration of Customs with a working citation.

• Agent-native by design. The primary interface is a complete natural-language question, not a thin keyword fan-out to Google, Bing, or Baidu.
• Model-native search backends. ARK, Gemini, Grok, DeepSeek, Responses, Messages, Zhipu Chat Search, and Codex Alpha can combine web retrieval with model-generated synthesis and explicit citations.
• Agent search providers. Exa, Parallel, Brave, Perplexity, Tavily, You.com, and Zhipu Web Search expose search APIs intended to provide structured, citation-friendly, or context-ready evidence to downstream agents.
• One provider-neutral contract. Every backend is available through the same MCP tool, CLI, Python API, and normalized results; model-backed providers may also return an answer.
• Independent providers. Selected providers run concurrently, and one provider's failure never discards another provider's successful result.
• DDGS remains a simple fallback. DDGS is the only conventional search backend; it requires no API key and keeps the project usable without paid provider credentials. Exa and Parallel are also keyless by default.
• No telemetry, no shared secrets. Provider keys stay in runtime environment variables; there is no shared API-key service.

Providers

The provider list is intentionally split by the kind of search capability it provides. Only DDGS is a conventional search backend; the other two groups are built around model-native grounding or agent-facing search services.

Free, keyless defaults: DDGS, Exa, and Parallel all work without an API key. Exa and Parallel automatically use their free MCP transports until a paid API key is provided.

Traditional search backend

| Provider | Website | Search backend | API key | Enabled by default | | --- | --- | --- | --- | :---: | | DDGS | DuckDuckGo | Conventional DuckDuckGo search | Free · no key required | Yes |

Model providers

These providers use a model-native search or grounding surface. Their responses can include a model-generated answer together with citations or other explicit search evidence.

| Provider | Website | Model-native search surface | API key | Enabled by default | | --- | --- | --- | --- | :---: | | ARK | Volcengine Ark | Responses API with Doubao web-search grounding | ARK_API_KEY | No | | Codex Alpha (experimental) | Alpha Search-compatible gateway | Model-backed Alpha Search surface | AGENT_WEB_SEARCH_CODEX_ALPHA_API_KEY | No | | DeepSeek | DeepSeek API | Anthropic Messages API with native web search | DEEPSEEK_API_KEY | No | | Gemini | Google AI | Gemini Google Search grounding | GEMINI_API_KEY | No | | Grok | xAI | xAI web search and X Search | XAI_API_KEY | No | | Responses | Responses API-compatible gateway | Generic OpenAI Responses API with web search grounding | AGENT_WEB_SEARCH_RESPONSES_API_KEY | No | | Messages | Messages API-compatible gateway | Generic Anthropic Messages API with web search grounding | AGENT_WEB_SEARCH_MESSAGES_API_KEY | No | | Zhipu Chat Search | Zhipu AI | GLM Chat Completions with native web search | ZHIPU_CHAT_SEARCH_API_KEY | No |

Agent search providers

These providers expose search services for agent consumption: natural-language queries, structured source rows, high-signal excerpts, or citation-friendly metadata rather than a conventional search-page experience.

| Provider | Website | Agent-facing search surface | API key | Enabled by default | | --- | --- | --- | --- | :---: | | Exa | Exa | Semantic Search API or free MCP fallback | Free without key · optional EXA_API_KEY | Yes | | Parallel | Parallel | Context-oriented search API or free MCP | Free without key · optional PARALLEL_API_KEY | Yes | | Brave | Brave Search | Structured Web Search API | BRAVE_SEARCH_API_KEY | No | | Perplexity | Perplexity API | Native structured Search API | PERPLEXITY_API_KEY | No | | Tavily | Tavily | Agent-oriented Search API | TAVILY_API_KEY | No | | You.com | You.com API | Unified web and news Search API | YDC_API_KEY | No | | **Zhipu Web Sear