JerryLiu369/agent-web-search

**Agent-native web search — model-native grounding and agent search APIs behind one provider-neutral contract.**
**English** | 简体中文
One-click remote MCP
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
Shared interface · Other interfaces · Troubleshooting · FAQ · Architecture · Development
---
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 " "),
> 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.
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):
Install
Install once into your global user environment (recommended):
Verify
> **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,