AgentWebSearch

中文 | English | 日本語

API-free public-web search and article reading for AI agents.

What it does

• Searches public web pages without an API key.
• Reads article text from public URLs.
• Uses direct Python HTTP first, then a fresh private Playwright Chromium process when browser rendering is needed.
• Supports batches with offset and exclude_urls so later searches avoid URLs returned in earlier batches.
• Reports CAPTCHA, login, paywall, unavailable, and non-HTML pages honestly. It does not bypass verification or fabricate text.
• Does not open or control the user's visible browser, and does not persist cookies, query history, API keys, or browser profiles.

Tool surface

Tool	Purpose
agent_web_search	Search result titles, URLs, snippets, source engine, batch offset, and engine status.
agent_web_read	Extract title and readable text from up to 10 public URLs per call.

Search batches use this pattern:

batch 1: offset=0,  limit=10
batch 2: offset=10, limit=10, exclude_urls=<URLs from batch 1>
batch 3: offset=20, limit=10, exclude_urls=<URLs from batches 1 and 2>

The requested amount is a maximum, not a promise: public search pages may return fewer new results or challenge automated access.

Backends

1. direct — Python requests; no API key.
2. headless_browser — ephemeral Playwright Chromium; no visible window or user-browser control.
3. auto — direct first, headless fallback when direct access fails or produces no new results.

Hermes Agent

hermes plugins install FirmaSpring/AgentWebSearch --enable

Optional browser backend:

pip install 'playwright>=1.45'
playwright install chromium

MCP server

MCP uses the same API-free Python search and reader core. MCP itself is only the local tool protocol; it does not require a search API or API key.

uv sync --extra mcp --extra browser --group dev
playwright install chromium
.venv/Scripts/agent-web-search-mcp.exe

Example Windows MCP client configuration:

{
  "mcpServers": {
    "agent-web-search": {
      "command": "C:\\path\\to\\AgentWebSearch\\.venv\\Scripts\\agent-web-search-mcp.exe",
      "args": []
    }
  }
}

The stdio server exposes web_search and web_read, opens no listening port, stores no MCP session state, and exits with its client.

Cross-agent support

The MCP server is protocol-tested with the MCP Python SDK 2.x stdio client: initialization, tool discovery, web_search, and web_read all run through real MCP messages.

Integration	Status	Notes
Hermes Agent native plugin	Available	This repository ships it.
Generic stdio MCP client	Protocol verified	web_search and web_read are available.
OpenCode / VS Code / Gemini CLI	MCP-capable	Official documentation supports MCP servers; host configuration still needs per-host verification.
OpenClaw / Claude Code / Codex / Cursor / Cline / Continue	Candidate MCP hosts	Configure the stdio server only where the current host release supports it; label verified only after testing that host.

Privacy

Search queries are sent to the selected public search engine. Reading a URL sends a request to that URL. No API key is needed by this plugin.

Development

python -m pytest -q

License

MIT