Searxng Deepdive

io.github.burakaydinofficial由 GitHub 帳號 burakaydinofficial 發布v0.4.1更新於 Oct 24, 2026

MCP server for SearXNG with engine targeting, multi-page fanout, and HTML→Markdown URL reading.

概覽

AI 產生的概覽

讓助理透過 SearXNG 進行可指定引擎與類別的網頁搜尋、多頁抓取,並將網頁讀取為 Markdown。

可以做什麼
針對 SearXNG 執行個體註冊四個工具:一般搜尋、可指定引擎的 search_on_engines、可指定類別的 search_by_category,以及把 HTTP(S) 網址的 HTML、JSON、YAML 或 TOML 轉成 Markdown 的 web_url_read。搜尋工具支援分頁、單次多頁抓取、時間範圍、語言、安全搜尋,以及精簡或完整的结果格式。工具描述會在啟動時依所設定執行個體的即時引擎與類別清單產生,無效的引擎或類別名稱會回傳提示。
適用情境
適合需要自架、重視隱私的網頁研究,而非託管搜尋 API 的情境:在指定引擎或類別上做定向搜尋、一次呼叫取得多頁結果,以及以節省 token 的方式閱讀文件、新聞或程式碼倉庫頁面。不適合 JavaScript 渲染的單頁應用或具反爬蟲保護的網站,這些頁面回傳的內容很少或為空。
執行需求
以 npm 套件(searxng-deepdive)形式透過 stdio 在本機執行,需要 Node.js 22 或更新版本。需要一個可連線的 SearXNG 執行個體,其基礎網址透過環境變數 SEARXNG_URL 設定,預設值為 MCP 用戶端。
安裝前請注意
web_url_read 會抓取模型提供的任意 HTTP(S) 網址,最多跟隨五次重新導向,因此在可連線私有網路的機器上可能觸及內網服務、連結本地位址或雲端中繼資料端點;可用 SEARXNG_DEEPDIVE_BLOCK_PRIVATE 與 SEARXNG_DEEPDIVE_ALLOWED_HOSTS 加以限制。搜尋查詢會原樣轉送給 SearXNG,由它負責上游流量。回傳的摘要與頁面文字屬於不可信的外部內容,可能帶有提示注入,應避免讓代理在無人複核的情況下直接依工具輸出採取行動。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Searxng Deepdive,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

searxng-deepdive

[Tests] [License: MIT]

An MCP server for SearXNG designed for LLM agents doing real research. Four tools with agent-friendly schemas, multi-page result fanout, lightweight URL→Markdown reading, and tool descriptions generated dynamically from the live engine pool of your SearXNG instance.

Why another mcp-searxng?

Existing packages are minimal — most expose a single search(query) tool with no way for the model to ask for more results, target specific engines, or constrain by category. The richer ones bake static descriptions, so the LLM never learns what's actually enabled on this instance. None of them treat agent-tool-selection ergonomics as a design priority.

searxng-deepdive opens those knobs up:

FeatureThisnpm mcp-searxng (ihor-sokoliuk)PyPI mcp-searxng (SecretiveShell)
Engine targeting✅ via search_on_engines❌❌
Category targeting✅ via search_by_category❌❌
Multi-page fanout in one call✅ via pages: N❌ (one page per call)❌
Pagination✅ via pageno✅❌
Compact response trim✅ via format: "compact"❌❌
Dynamic descriptions per instance✅ live engine list injected❌ static❌ static
Validation with cross-tool hints✅ engine-vs-category, case-insensitive❌❌
Zero-result hints✅ time_range / unresponsive engines / single-engine❌❌
URL reader (HTML→Markdown)✅ with TOC scan + section extraction✅ basic❌
Test suite✅ 102 unit + integrationminimal❌

Quickstart

Install via npx -y from any MCP client:

json
{  "mcpServers": {    "searxng": {      "command": "npx",      "args": ["-y", "searxng-deepdive"],      "env": { "SEARXNG_URL": "http://127.0.0.1:7979/" }    }  }}

SEARXNG_URL should point at your running SearXNG instance. Need one? The companion repo SearXNG-Compose ships a plug-and-play Docker stack tuned for LLM consumption.

Requirements: Node.js 22 or newer.

Tools

The server registers four tools. The LLM picks among them based on the descriptions below, augmented at startup with the live engine and category list from your instance.

search(query, [...])

Broad web search across the full enabled engine pool. Use when you don't have a specific source preference. Returns merged, deduplicated results across however many engines respond.

search_on_engines(query, engines, [...])

Search using only the specified engines (e.g. ["arxiv", "pubmed", "semantic scholar"]). The tool description registered with the MCP client includes the actual list of engines enabled on your instance — agents don't have to guess names. Validation rejects invalid names with a "did you mean" hint when they look like categories instead of engines.

search_by_category(query, categories, [...])

Search within specific categories — runs every engine tagged with each. Description includes the live category list and which engines belong to each. Same validation: invalid category names produce a clear error that points at search_on_engines when the offending value is actually an engine name.

web_url_read(url, [readHeadings, section, paragraphRange, startChar, maxLength])

Fetch a URL and convert its HTML to clean Markdown. Lightweight HTTP + HTML→Markdown (no headless browser) — handles ~80% of the static-HTML web (Wikipedia, docs sites, blogs, news, GitHub READMEs).

Token-efficient extraction modes (priority order, first set wins):

  • readHeadings: true — return only the heading list as a hierarchical TOC
  • section: "Installation" — return content under matching heading
  • paragraphRange: "3-7" — 1-indexed paragraph slice
  • startChar + maxLength — character window pagination

Recommended workflow for long pages: TOC scan first (readHeadings), then targeted read (section). Far more token-efficient than fetching the full page up front.

If readHeadings comes back with no entries (Reddit threads, comment sections, blog posts that use bold paragraphs instead of <h*> tags), the page is structurally flat — fall through to paragraphRange for sequential sampling, or just fetch without an extraction mode.

web_url_read also accepts JSON, YAML, and TOML content-types directly (spec files, package manifests, registry API responses, CI workflow YAML), so research agents can read these without the HTML-only stub.

For JS-rendered SPAs and bot-protected sites this tool returns minimal/empty content — fall back to a Chromium-backed reader (e.g. Crawl4AI) for those.

Common parameters across all search tools

  • pageno — 1-indexed starting page (default 1)
  • pages — multi-page fanout in one call (1–5, default 1)
  • time_range — day / week / month / year (warning: not all engines support this; some return empty when set)
  • language — BCP-47 code or all
  • safe_search — 0 / 1 / 2
  • format — compact (default) or full

Configuration

Env varDefaultMeaning
SEARXNG_URLhttp://127.0.0.1:8080Base URL of the SearXNG instance

Development

bash
git clone <this repo>cd searxng-deepdive          # or wherever you cloned tonpm installnpm run build                # tscnpm test                     # vitestSEARXNG_URL=http://127.0.0.1:7979 npm run probe    # exercise the SearXNG clientSEARXNG_URL=http://127.0.0.1:7979 npm run dev      # start the MCP stdio server

Pointing an MCP client at the source during development

Use tsx to run from src/ directly so you don't need to rebuild on every edit:

json
{  "mcpServers": {    "searxng": {      "command": "npx",      "args": ["-y", "tsx", "/absolute/path/to/searxng-deepdive/src/index.ts"],      "env": { "SEARXNG_URL": "http://127.0.0.1:7979/" }    }  }}

MCP clients cache the subprocess. When you edit code, the running server keeps the old behavior until the subprocess is killed and respawned. Quit the host (LM Studio, Claude Desktop, etc.) fully and reopen — closing the chat window alone usually isn't enough. Symptom of not doing this: a fix you just shipped doesn't appear to take effect.

Testing

npm test

Test coverage spans seven files:

  • normalize-name — case-insensitive name handling
  • validators — engine/category validation with cross-reference hints
  • zero-result-hint — every hint trigger and its inverse
  • trim-to-compact — response trimming + hint inclusion
  • descriptions — anti-pattern regex checks for the description copy that misled real models in earlier versions ("ignored by engines", "Default 'auto'", etc.) — failing build if they reappear
  • searxng-client — HTTP client with MockAgent: malformed JSON, HTML 502 pages, 429 rate-limit handling, multi-page fanout dedup, all-pages-fail throws
  • url-reader — extraction modes + HTTP integration

Design notes

  • Why four tools instead of one with optional engine/category params? Cleaner agent decision-making. With distinct tools the LLM sees explicit purposes; with one fat tool it has to remember when to set which optional flags. Trade-off: more entries in the MCP tool list, mostly identical handler code. Net: better agent ergonomics, especially for smaller models.

  • Why format: "compact" as default? SearXNG's full result objects are several times heavier than just url+title+content+engine. For the typical agent workflow (rank candidates, pick a few to fetch in detail), the compact form is what the LLM actually uses. format: "full" is one parameter away when you need scores, dates, authors, or DOI.

  • Why dynamic descriptions? Static descriptions either list every upstream engine (most aren't enabled on a given instance — wastes context) or list none (LLM has no idea what to put in engines). Live introspection of /config at server startup gives the LLM exactly the right hint for this instance.

  • Why convert silent-wrong into informatively-wrong? Real LM Studio testing showed agents repeatedly stuck in retry loops because failed searches looked successful (zero results, looked like "no matches"; or 60 garbage results, looked like the search ran). The validation + zero-result-hint pattern surfaces the actual cause every time. The description-anti-pattern test suite locks in copy that was empirically shown to mislead models.

Security notes

This package is designed to run locally, inside the user's trust boundary, alongside an MCP-speaking LLM client (Claude Desktop, LM Studio, Cursor, etc.). The trust model assumes:

  • the LLM is acting on the user's behalf
  • the user controls what model is connected to the server
  • the MCP transport is stdio, not exposed to remote callers

Within that boundary, two surfaces are worth knowing about:

  • web_url_read will fetch any HTTP(S) URL the model hands it, with up to five redirects. On a host that can route to private networks, the model can therefore reach intranet services, link-local addresses, or cloud-instance metadata endpoints (169.254.169.254, etc.). This is by design for a local research tool but means you should not run this MCP server in topologies where an untrusted party can pick the URLs (e.g. a hosted MCP gateway facing the public internet). If you do want to lock it down, set SEARXNG_DEEPDIVE_BLOCK_PRIVATE=1 to refuse private / loopback / link-local / metadata destinations — enforced on every redirect hop and against the actual dialed IP, so DNS rebinding can't slip past — and allow specific internal hosts back in with SEARXNG_DEEPDIVE_ALLOWED_HOSTS. Non-HTTP(S) schemes — including file:// — are always rejected, so the tool never reads local files. Body size is capped at 10 MB, a single request has a 45 s total deadline, and the returned Markdown is length-capped (paginate with startChar/maxLength), so a malformed or oversized upstream can't trivially exhaust memory or the caller's context window.

  • The search tools forward the model's query verbatim to SearXNG. SearXNG is the trust boundary for upstream engine traffic; this package does not add additional rate-limiting or query rewriting.

  • Tool output is adversarial input — prompt injection is possible. Search-result snippets and the Markdown returned by web_url_read both contain text the model will read as part of its working context. A page or snippet you don't control can carry instructions ("ignore previous instructions and …"). This isn't a defect in this MCP server — it's inherent to any tool that returns external text — but agent loops that auto-act on tool output without human review are the threat model. Treat tool output as untrusted input, especially for web_url_read against URLs the model picked rather than the user.

This package is provided as-is under MIT with no warranty or liability for damages — see LICENSE. Report suspected vulnerabilities privately via GitHub Security Advisories rather than opening a public issue. See SECURITY.md.

License

MIT — see LICENSE.

來源:README.md,提交 e730aeb

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.4.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分