Skip to content
Back to search

agent-search-mcp

Free-first Chinese and English web search MCP using zero-key sources and inspectable evidence.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lennney--agent-search-mcp/badge.svg)](/listings/lennney--agent-search-mcp)

HTML

<a href="/listings/lennney--agent-search-mcp"><img src="/api/listings/lennney--agent-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx -y agent-search-mcp

Requires Node.js >= 18.17. The default runtime does not require a browser, database, Python, or a search API account.

Connect an MCP client

Use this stdio configuration in MCP clients that accept `mcpServers` JSON, including Claude Desktop, Cursor, VS Code, and Windsurf:

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["-y", "agent-search-mcp"]
    }
  }
}

Claude Code and Codex can register the same `npx -y agent-search-mcp` stdio command through their MCP settings.

Add the optional Agent Skill

After connecting the MCP server, Agent Skills-compatible clients can install the repository-owned routing guide:

npx skills add lennney/agent-search-mcp --skill agent-search

Invoke it with a request such as `Use $agent-search to verify this claim with official sources.` The [Agent Search Skill](./skills/agent-search/SKILL.md) chooses one of four bounded paths: quick discovery, stricter verification, Chinese-source search, or extraction of a selected URL. It checks that the needed MCP tool exists and asks before any install or configuration change. Installing the Skill does not start or configure the MCP server.

Example: inspect a bounded search result

After building the local package, run a CLI query without adding a provider key:

npm run build
fasm search "MCP server without an API key" --json

The response contract keeps result evidence, `meta.execution`, and `partialFailures` separate. A provider timeout or challenge remains visible to the agent instead of being converted into an unexplained empty result. This is a contract example, not a live availability or search-quality benchmark.

After a global install, check the local runtime without making a search request:

npm install -g agent-search-mcp
fasm doctor

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 368 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Agent Search MCP: Free-first Web Search with Inspectable Evidence
  2. **A Node.js MCP server and CLI for English and Chinese web search.**
  3. Agent Search MCP starts without an API key. It returns compact multi-source
  4. evidence, records provider failures, and bounds work with request and evidence
  5. budgets. Paid providers run only when policy and credentials allow.
  6. [![npm version](https://img.shields.io/npm/v/agent-search-mcp)](https://www.npmjs.com/package/agent-search-mcp)
  7. [![npm downloads](https://img.shields.io/npm/dm/agent-search-mcp)](https://www.npmjs.com/package/agent-search-mcp)
  8. [![GitHub stars](https://img.shields.io/github/stars/lennney/agent-search-mcp)](https://github.com/lennney/agent-search-mcp/stargazers)
  9. [![CI](https://github.com/lennney/agent-search-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lennney/agent-search-mcp/actions)
  10. [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
  11. [![Glama](https://glama.ai/mcp/servers/lennney/agent-search-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lennney/agent-search-mcp)
  12. [中文文档](README_zh.md) · [Product page](https://take-a-deep-breath0.com/en/agent-search-mcp) · [Benchmarks](./benchmarks/) · [Architecture](./docs/architecture.md) · [CHANGELOG](./CHANGELOG.md)
  13. ---
  14. ## Install
  15. ```bash
  16. npx -y agent-search-mcp
  17. ```
  18. Requires Node.js >= 18.17. The default runtime does not require a browser,
  19. database, Python, or a search API account.
  20. ### Connect an MCP client
  21. Use this stdio configuration in MCP clients that accept `mcpServers` JSON,
  22. including Claude Desktop, Cursor, VS Code, and Windsurf:
  23. ```json
  24. {
  25. "mcpServers": {
  26. "agent-search": {
  27. "command": "npx",
  28. "args": ["-y", "agent-search-mcp"]
  29. }
  30. }
  31. }
  32. ```
  33. Claude Code and Codex can register the same `npx -y agent-search-mcp` stdio
  34. command through their MCP settings.
  35. ### Add the optional Agent Skill
  36. After connecting the MCP server, Agent Skills-compatible clients can install
  37. the repository-owned routing guide:
  38. ```bash
  39. npx skills add lennney/agent-search-mcp --skill agent-search
  40. ```
  41. Invoke it with a request such as `Use $agent-search to verify this claim with
  42. official sources.` The [Agent Search Skill](./skills/agent-search/SKILL.md)
  43. chooses one of four bounded paths: quick discovery, stricter verification,
  44. Chinese-source search, or extraction of a selected URL. It checks that the
  45. needed MCP tool exists and asks before any install or configuration change.
  46. Installing the Skill does not start or configure the MCP server.
  47. ### Example: inspect a bounded search result
  48. After building the local package, run a CLI query without adding a provider key:
  49. ```bash
  50. npm run build
  51. fasm search "MCP server without an API key" --json
  52. ```
  53. The response contract keeps result evidence, `meta.execution`, and
  54. `partialFailures` separate. A provider timeout or challenge remains visible to
  55. the agent instead of being converted into an unexplained empty result. This is
  56. a contract example, not a live availability or search-quality benchmark.
  57. After a global install, check the local runtime without making a search request:
  58. ```bash
  59. npm install -g agent-search-mcp
  60. fasm doctor
  61. ```
  62. ## Why Agent Search MCP
  63. | Need | Product behavior |
  64. |---|---|
  65. | Free web search | Zero-key sources work without an API account |
  66. | Provider cost control | Paid providers run only under an explicit routing policy |
  67. | Token cost control | Compact output and one evidence budget bound response size |
  68. | Multi-source evidence | Results retain provenance, relevance, provider-family count, and partial failures |
  69. | Chinese web search | Sogou and Baidu handle Chinese queries without a translation layer |
  70. | Lightweight self-hosting | Pure Node.js runtime with stdio, Streamable HTTP, and CLI access |
  71. ### The difference from a plain multi-engine wrapper
  72. | Plain multi-engine aggregation | Agent Search MCP |
  73. |---|---|
  74. | Returns N deduplicated results | Returns results plus the number of **independent sources** (provider families, not adapter names) |
  75. | A provider failure quietly drops some results | Every failure stays in `partialFailures` (timeout, rate limit, challenge, permission, budget) |
  76. | Stops when the result count looks sufficient | Stops only after a quality gate (count, relevance, confidence, source coverage) and returns the `stop_reason` |
  77. | Fixed-size output | One shared evidence budget bounds response tokens; compact text keeps provenance |
  78. | One adapter counts as one source | The same upstream through several adapters never inflates `source_count` |
  79. The one-minute offline demo replays these differences through the production
  80. evidence scorer and formatter:
  81. ### Inspect the search evidence
  82. Each JSON response includes one Search Evidence Packet. It answers the routing
  83. questions an agent needs before it uses a result:
  84. | Question | Response field |
  85. |---|---|
  86. | Which adapters ran? | `meta.execution.searched_engines` |
  87. | Why did the router stop? | `meta.execution.stop_reason` and `meta.execution.quality_gate` |
  88. | Did the request hit a work limit? | `meta.execution.budget` |
  89. | Was evidence truncated? | `meta.evidence_budget` |
  90. | Did an upstream provider fail? | `partialFailures` |
  91. | Do multiple adapters represent independent sources? | `results[].source_count` counts provider families, not adapter names |
  92. Run the one-minute offline contract demo:
  93. ```bash
  94. npm run demo:evidence
  95. npm run demo:evidence -- --json
  96. ```
  97. It replays three synthetic scenarios through the production evidence scorer,
  98. formatter, and MCP output helper: same-family adapter overlap, visible fallback
  99. failure, and a bounded quality-gate stop. It makes no live availability or
  100. search-quality claim and performs no network request.
  101. The default `free_first` policy never spends a configured API credential.
  102. `free_only` blocks paid providers. `quality_escalation` can call one configured
  103. paid provider after free evidence misses the quality gate, while `paid_first`
  104. tries that provider before the free fallback.
  105. Request budgets cap adapter attempts, elapsed time, and admitted results.
  106. The evidence budget caps query-relevant passages across the complete response.
  107. Compact mode keeps full detail for the first results and reduces later entries
  108. to source-preserving references.
  109. ### Measured token reduction
  110. The checked-in bilingual fixture measures formatting with a locked tokenizer:
  111. | Output | Average tokens per query | Savings vs normal |
  112. |---|---:|---:|
  113. | Normal | 2396.0 | |
  114. | Compact | 1650.1 | 31.1% |
  115. | Compact+ | 1633.0 | 31.8% |
  116. This fixture verifies output formatting and evidence-packet behavior. It does
  117. not measure live engine availability or search quality. See the
  118. [benchmark method and limitations](./benchmarks/#reproducible-fixture-replay).
  119. ## How the search router works
  120. ```mermaid
  121. flowchart LR
  122. A["AI agent"] --> M["MCP search tools"]
  123. M --> P["Provider and request policy"]
  124. P --> F["Zero-key sources"]
  125. P --> O["Optional paid provider"]
  126. F --> E["Deduplicate, rank, and preserve failures"]
  127. O --> E
  128. E --> B["Evidence and token budget"]
  129. B --> R["Compact multi-source result"]
  130. ```
  131. The router evaluates each search batch against separate result, relevance,
  132. confidence, and provider-family gates. It stops after the evidence passes those
  133. gates and exposes the decision in `meta.execution`. Provider failures stay
  134. visible in `partialFailures`, so an empty result cannot hide an upstream error.
  135. The [competitive landscape (2026-08-07)](./docs/research/2026-08-07-competitive-landscape-and-product-gaps.md)
  136. maps the crowded baseline and the product gaps. It records source dates and
  137. fixed commits for facts that can change. The
  138. [2026-08-10 update](./docs/research/2026-08-10-competitive-landscape-update.md)
  139. adds competitor activity since then: direct local competitors are dormant, and
  140. token-efficient evidence is becoming an industry-explicit lever. The earlier
  141. [source-level product comparison](./docs/research/2026-07-26-agent-search-product-architecture.md)
  142. contains the architecture-specific evidence.
  143. ---
  144. <!-- BEGIN GENERATED CAPABILITY MATRIX -->
  145. ## Engines
  146. The runtime registers 17 adapters: 9 zero-key adapters and 8 optional API adapters.
  147. | Engine | Access | Languages | Role |
  148. |---|---|---|---|
  149. | DuckDuckGo | Zero-key | en | General Web Search |
  150. | Sogou Search | Zero-key | zh | Chinese Web Search |
  151. | Bing | Zero-key | en, zh | Multilingual Web Search |
  152. | Baidu | Zero-key | zh | Chinese Web Search |
  153. | Wikipedia | Zero-key | en, zh, ja, de, fr, es, auto | Encyclopedic references |
  154. | Startpage | Zero-key | en, auto | Privacy-oriented Web Search |
  155. | Yandex | Zero-key | ru, en, auto | Russian and international Web Search |
  156. | Mojeek | Zero-key | en, auto | Independent privacy-oriented index |
  157. | Wiby | Zero-key | en | Independent small-Web index |
  158. | Brave Search | `BRAVE_API_KEY` | en, zh | Optional commercial Web Search |
  159. | Tavily Search | `TAVILY_API_KEY` | en, zh | Optional agent-oriented Search |
  160. | Exa Search | `EXA_API_KEY` | en, zh | Optional neural Search |
  161. | Keenable Search | `KEENABLE_API_KEY` | en, auto | Optional independent agent-oriented Search |
  162. | You.com Search | `YDC_API_KEY` | en, zh | Optional commercial Web Search |
  163. | Tencent Web Search API | `TENCENT_WSA_API_KEY` | zh | Optional official Chinese Web Search |
  164. | Bocha Web Search | `BOCHA_API_KEY` | zh, en | Optional Chinese-first AI Search |
  165. | Serper Google Search | `SERPER_API_KEY` | en, zh, auto | Optional Google SERP Search |
  166. ## Tools
  167. | Tool | Description | Best for |
  168. |---|---|---|
  169. | `free_search` | Multi-engine Web Search with bounded fallback | Quick facts and general discovery |
  170. | `free_search_advanced` | Filtered waterfall search and optional enrichment | Domain policy and progressive verification |
  171. | `free_extract` | Extract a URL as clean Markdown | Reading complete source pages |
  172. | `fetch_github_readme` | Fetch a public GitHub repository README | Project documentation |
  173. | `fetch_csdn_article` | Fetch a CSDN article | Chinese technical articles |
  174. | `fetch_juejin_article` | Fetch a Juejin article | Chinese developer articles |
  175. | `search_with_synthesis` | Search evidence with an LLM synthesis hint | Agent-authored answers from cited evidence |
  176. ### Capability controls
  177. | Environment | Default | Purpose |
  178. |---|---|---|
  179. | `ENABLED_TOOLS / DISABLED_TOOLS` | all / none | Tool registration allowlist and denylist; deny wins |
  180. | `ALLOWED_ENGINES / DENIED_ENGINES` | all / none | Engine execution allowlist and denylist; deny wins |
  181. | `SEARCH_PROVIDER_MODE` | free_first | Default routing: free_first, quality_escalation, paid_first, or free_only |
  182. | `PAID_ENGINE_ORDER` | brave,exa,tavily,keenable,youcom,tencent_wsa,bocha,serper | Selects the first configured optional provider; not a quality claim |
  183. | `SEARCH_BUDGET_MAX_CALLS` | 16 | Adapter-attempt budget |
  184. | `SEARCH_BUDGET_MAX_ELAPSED_MS` | 30000 | End-to-end elapsed-time budget |
  185. | `SEARCH_BUDGET_MAX_RESULTS` | 100 | Admitted raw-result budget |
  186. | `EVIDENCE_BUDGET_CHARS` | 1200 | Evidence-character budget |
  187. <!-- END GENERATED CAPABILITY MATRIX -->
  188. `search_with_synthesis` uses the same canonical `structuredContent` evidence
  189. packet as the primary search tools and adds `prompt_hint`; its text content is
  190. only a compact compatibility view. Execution metadata distinguishes scheduled
  191. adapters from retry-inclusive adapter attempts. `http_requests` is `null` until
  192. all adapter transports can report it without false precision.
  193. Wiby is a genuine zero-key source backed by its official JSON API and is used
  194. late in the free waterfall as an independent small-Web supplement. Optional
  195. providers require user credentials; any signup credit or trial quota is
  196. provider-controlled and is not treated as permanent free access.
  197. All tools are read-only and idempotent. Search cancellation reaches rate-limit
  198. waits, retries, provider requests, and optional enrichment. Enrichment can
  199. improve a snippet but cannot increase source confidence or independent source
  200. count.
  201. `free_search_advanced.time_range` remains in the compatibility schema. The
  202. server returns `UNSUPPORTED_FILTER` before searching because the general web
  203. providers do not share one enforceable recency contract.
  204. ---
  205. ## Configuration
  206. The generated capability table above lists the default request budgets. These
  207. settings cover the common deployment choices:
  208. | Goal | Environment variables |
  209. |---|---|
  210. | Add an optional provider | `BRAVE_API_KEY`, `TAVILY_API_KEY`, `KEENABLE_API_KEY`, `EXA_API_KEY`, `YDC_API_KEY`, `TENCENT_WSA_API_KEY`, `BOCHA_API_KEY`, or `SERPER_API_KEY` |
  211. | Choose spend policy | `SEARCH_PROVIDER_MODE`, `PAID_ENGINE_ORDER` |
  212. | Reduce response tokens | `OUTPUT_STYLE=compact`, `MAX_FULL_RESULTS`, `SNIPPET_LENGTH`, `EVIDENCE_BUDGET_CHARS` |
  213. | Restrict tools or engines | `ENABLED_TOOLS`, `DISABLED_TOOLS`, `ALLOWED_ENGINES`, `DENIED_ENGINES` |
  214. | Use an explicit proxy | `DUCKDUCKGO_PROXY_URL`, `SOGOU_PROXY_URL`, `MOJEEK_PROXY_URL`, `WIBY_PROXY_URL`, or `USE_PROXY=true` with `PROXY_URL` |
  215. | Use a user-owned proxy pool | `DUCKDUCKGO_PROXY_URLS`, `SOGOU_PROXY_URLS`, `MOJEEK_PROXY_URLS`, or `WIBY_PROXY_URLS` as a JSON array of 2-16 HTTP(S) proxy URLs |
  216. | Persist the exact-result cache | `SEARCH_CACHE_DIRECTORY`, `SEARCH_CACHE_TTL_MS`, `SEARCH_CACHE_MAX_ENTRIES` |
  217. | Enable optional semantic processing | `SEMANTIC_DEDUP`, `SEMANTIC_RERANK`, `DEDUP_THRESHOLD`, `RERANK_TOP_K` |
  218. Adding an API key does not authorize paid traffic. The routing policy controls
  219. provider use. The default exact-result cache stays in memory; setting
  220. `SEARCH_CACHE_DIRECTORY` opts into local persistence. Semantic processing is
  221. the only optional feature that uses Python and Model2Vec.
  222. Proxy pools select a deterministic first exit from the logical query and keep
  223. multi-step provider requests sticky. Only a transport failure can move to the
  224. next configured exit; a failed transport is cooled for 60 seconds. HTTP
  225. responses, including 403, 429, and challenge pages, never trigger proxy
  226. switching and continue through the provider's existing cooldown contract.
  227. Engine-specific single-proxy variables take precedence over their pool. Proxy
  228. credentials are never printed by `fasm doctor`.
  229. ### HTTP deployment
  230. HTTP mode requires `HTTP_AUTH_TOKEN` unless you set
  231. `HTTP_ALLOW_UNAUTHENTICATED=true`. Browser requests with an `Origin` header must
  232. match `ALLOWED_ORIGINS`. See the [HTTP deployment guide](./docs/http-deployment.md)
  233. for TLS termination, token rotation, and reverse-proxy examples.
  234. ---
  235. ## CLI
  236. The package includes the `fasm` CLI:
  237. ```bash
  238. fasm search "TypeScript MCP server"
  239. fasm search "query" --count 5 --engines bing,baidu,youcom --json
  240. fasm extract "https://example.com"
  241. fasm extract "https://example.com" --json
  242. fasm doctor
  243. fasm doctor --json
  244. HTTP_AUTH_TOKEN=change-me MODE=http npx agent-search-mcp
  245. ```
  246. `fasm doctor` reads local configuration without network probes and never prints
  247. credential or proxy values.
  248. ---
  249. ## Documentation and evidence
  250. | Document | Contents |
  251. |---|---|
  252. | [System architecture](./docs/architecture.md) | Routing, evidence, provider families, and configuration |
  253. | [Competitive landscape (2026-08-10)](./docs/research/2026-08-10-competitive-landscape-update.md) | Competitor activity through 2026-08-10, positioning, and improvement priorities |
  254. | [Competitive landscape (2026-08-07)](./docs/research/2026-08-07-competitive-landscape-and-product-gaps.md) | Baseline competitors, expectations, and product gaps snapshot |
  255. | [Product comparison](./docs/research/2026-07-26-agent-search-product-architecture.md) | Source-level review of Agent search products |
  256. | [Benchmarks](./benchmarks/) | Token fixture, live-run scope, and quality evaluation method |
  257. | [v3.2.0 release notes](./docs/releases/v3.2.0.md) | Provider policy, budgets, and migration notes |
  258. | [Earlier release candidate evidence](./docs/evidence/2026-07-26-release-candidate-smoke.md) | Pre-expansion packed-install matrix and limitations |
  259. | [MCP 2026 readiness](./docs/plans/2026-07-25-mcp-ecosystem-and-2026-readiness.md) | Isolated protocol experiment and remaining gates |
  260. ## Companion: Slim Guard
  261. Agent Search controls retrieval work and compresses search evidence.
  262. [mcp-slim-guard](https://github.com/lennney/mcp-slim-guard) sits between an
  263. agent and MCP servers to handle tool-schema compression and security policy.
  264. ```bash
  265. npm install -g mcp-slim-guard
  266. ```
  267. ---
  268. ## Development
  269. ```bash
  270. git clone https://github.com/lennney/agent-search-mcp.git
  271. cd agent-search-mcp
  272. npm install
  273. npm run build
  274. npm test
  275. npm run dev # stdio mode
  276. npm run dev:http # HTTP mode (port 3000)
  277. ```
  278. The stable package supports Node.js 18, 20, and 22. The isolated MCP 2026
  279. experiment requires Node.js 20 or newer.
  280. ---
  281. ## License
  282. [Apache 2.0](LICENSE)
  283. Based on [open-websearch](https://github.com/Aas-ee/open-websearch) by Aas-ee.
  284. If Agent Search MCP helps your agent, [star the repository](https://github.com/lennney/agent-search-mcp)
  285. so other developers can find the project.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.