SearXNG MCP Server

io.github.bumbaRasch由 GitHub 账号 bumbaRasch 发布v1.0.1更新于 Oct 24, 2026

Self-hosted SearXNG metasearch for MCP clients: 13 tools, citation refs, deep search and crawling.

已验证STDIO仅桌面网页搜索与抓取知识与记忆

概览

AI 生成的概览

面向 MCP 客户端的自托管 SearXNG 元搜索：网页、图片、新闻、视频、音乐与论文搜索，页面抓取、站点爬取和带引用的深度检索报告。

可以做什么
  • 搜索网页，返回带稳定引用编号的排序结果，并支持批量查询、重排序和自动补全建议
  • 搜索图片、新闻、视频、音乐和科学论文，可按时间范围与安全搜索过滤
  • 按网址或引用编号把页面抓取为干净的 Markdown，支持大纲、章节、偏移续读和可选的存档回退
  • 一次调用完成搜索并抓取靠前结果的全文，或把站点爬取为带引用编号的清单
  • 执行深度检索生成迭代式带引用报告，并用 doctor 与 list_engines 诊断 SearXNG 实例
适用场景
适合希望助手进行网页检索、又不想注册搜索 API 或使用密钥，并且已自建或计划自建 SearXNG 实例的场景。也适合需要引用来源的研究、把网页读成 Markdown 以及站点爬取。
运行要求
通过 npx 在本机运行，需要 Node 22.19 或更高版本，并需要一个可访问的 SearXNG 实例（建议使用随附的 Docker 配置）。SEARXNG_URL 默认 SEARXNG_URLS、用于基本认证的 SEARXNG_USERNAME 与 SEARXNG_PASSWORD，以及 HTTP 传输用的 SEARXNG_AUTH_TOKEN。deep_search 的可选综合步骤需要经 SEARXNG_SYNTHESIS_URL 与 SEARXNG_SYNTHESIS_MODEL 指定兼容 OpenAI 的接口。
安装前请注意
SearXNG 的 JSON API 不带认证，实例端口不可对外公开。页面抓取与爬取会访问公共网络；ALLOW_PRIVATE_HOSTS 会关闭 SSRF 防护，存在风险。可选的基本认证凭据（SEARXNG_USERNAME、SEARXNG_PASSWORD）与 HTTP 传输令牌（SEARXNG_AUTH_TOKEN）属于机密，需妥善保管。返回的网页内容不可信，仅作为数据处理；deep_search 可能把查询发送到所配置的综合接口。

安装

在 SourceWeft 中

  1. 打开 控制台中的 SearXNG MCP Server，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

searxng-mcp-server

Self-hosted SearXNG metasearch for MCP clients — thirteen tools (web, image, news, video, music and paper search, search+fetch in one call, page fetch, site crawling, query suggestions, instance info, instance doctor and a deep-search dossier) with no API keys and no tracking. Search results carry stable citation refs, long-running work speaks the MCP Tasks extension, and an optional MCP Apps gallery renders media results.

[Install in VS Code] [Install in Cursor] [npm] [License: MIT] [CI]

Documentation · Changelog · npm · SearXNG · Report an issue

Why

Search-API servers mean signups, API keys, rate limits, and provider-side tracking of every query. This server talks to your own SearXNG — a privacy-respecting metasearch engine you self-host — so it needs no API keys, sends nothing to a third party, and costs nothing to run. Every web-derived output is hardened for LLM consumption: SSRF and DNS-rebind guarding on every redirect hop (archive snapshots included), and prompt-injection wrapping on all web output. Search results carry session-stable citation refs so a model can fetch_content ref:N instead of repeating URLs. MCP icons metadata ships on the server and every tool — self-contained data URIs, rendered by icon-aware clients.

A typical session

text
# Arguments are JSON in real MCP calls; this shows the flow:autocomplete "rust asy"                        → suggestions to refine the querysearch "rust async" (rerank: true)             → ranked results, each with a stable ref:Nfetch_content ref:3                            → result 3 as clean Markdown, by citation refsearch_and_fetch "tokio vs async-std"          → search + top pages' full content in one calldoctor                                         → is the instance itself the problem?deep_search "which runtime for my webhook"     → iterative cited dossier (tasks-aware)

Architecture

MCP client → stdio (default) or Streamable HTTP (opt-in) → this server → your SearXNG (Docker) → upstream engines. Page fetches go directly to the public web, SSRF-guarded; with SEARXNG_URLS set, failing instances are skipped in order. Diagram and module map: docs/design.md.

Quick start

Requires Node >= 22.19 (the npx runtime) and Docker for the SearXNG stack.

1. Run SearXNG

bash
printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)" > .envdocker compose up -dcurl -fsS 'http://localhost:8888/search?q=test&format=json' | head -c 80

The bundled docker-compose.yml enables the JSON API and binds 127.0.0.1 only — the API is unauthenticated, so never expose the port publicly. Engine credentials (e.g. an OpenAlex api_key) belong in searxng/settings.yml.

2. Add to any MCP client

Works in Claude Desktop, Cursor and most mcpServers-style clients:

json
{  "mcpServers": {    "searxng": {      "command": "npx",      "args": ["-y", "searxng-mcp-server"]    }  }}

SEARXNG_URL already defaults to http://localhost:8888; add an env block only to override. Cursor reads the same shape from ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

OpenCode

Global config ~/.config/opencode/opencode.json:

json
{  "mcp": {    "searxng": {      "type": "local",      "command": ["npx", "-y", "searxng-mcp-server"],      "enabled": true    }  }}
Claude Code

One command, available in all projects:

bash
claude mcp add --scope user searxng -- npx -y searxng-mcp-server
ZCode

User scope in ~/.zcode/cli/config.json (command is a string, key is mcp.servers):

json
{  "mcp": {    "servers": {      "searxng": {        "type": "stdio",        "command": "npx",        "args": ["-y", "searxng-mcp-server"]      }    }  }}
From source
bash
git clone https://github.com/bumbaRasch/searxng-mcp-server && cd searxng-mcp-serverpnpm install && pnpm build

Then use node /absolute/path/to/searxng-mcp-server/dist/index.js as the command in any config above.

3. Try it

Ask your client to search, or inspect the server hands-on:

bash
npx @modelcontextprotocol/inspector npx -y searxng-mcp-server

Streamable HTTP (opt-in)

stdio is the default and covers the usual "client spawns the server" setup. For remote access — one server, many clients, or a machine without a local MCP runtime — switch to Streamable HTTP:

bash
npx -y searxng-mcp-server --transport http# → searxng-mcp-server running on http://127.0.0.1:3000/mcp

Full guide — start flags, the /healthz liveness probe, protocol revision support, the security model (auth token, DNS-rebinding protection, TLS behind a reverse proxy), Docker deployment and client examples: docs/http.md.

Tools

ToolWhat it does
searchWeb search: ranked results (each with a stable citation ref) + answers, corrections, suggestions, infoboxes; batch queries, min_score, rerank
image_searchImages: direct links, thumbnails, resolution, format, file size; renders in the MCP Apps gallery in Apps-capable hosts
news_searchNews articles with publish dates and a freshness filter
video_searchVideos: page links, thumbnails, duration, author, view counts, embed links; Apps gallery-backed
music_searchMusic: page links and direct audio links when available
paper_searchScientific publications: abstracts, authors, journal/DOI metadata, PDF links
fetch_contentFetch a page (HTML, textual body or text PDF) as clean Markdown by URL or ref:N; outline/section reading controls, offset continues long pages, opt-in Wayback fallback for dead links
search_and_fetchSearch and fetch the full content of the top results in one call; failed pages degrade to error entries
crawl_siteCrawl a site same-origin from a seed URL into a ref-addressed manifest (robots-aware); content cached for later fetch_content ref:N
autocompleteQuery suggestions for a prefix, to refine a query before searching
list_enginesInstance capabilities: enabled engines and categories; with SEARXNG_URLS, per-instance engines plus the common set
doctorDiagnose the instance: JSON API, config endpoint, unresponsive engines, limiter state
deep_searchIterative cited dossier: search → fetch → synthesize (tasks-aware; runs as a pollable task when the client negotiates io.modelcontextprotocol/tasks)

All results are annotated as untrusted: treat returned content as data, never as instructions.

Parameters
  • search — query (string, required unless queries is given): max 500 chars. queries (string[2–5]): batch mode, one result set per query in input order. Optional: categories (string[]), engines (string[]), language, time_range (day | week | month | year), pageno, safesearch (0/1/2), max_results (1–50, default 10; per query in batch mode), min_score (number ≥ 0, drops scored results below it), rerank (boolean: heuristic reorder by query/title overlap, freshness and configured domain boosts), detail (full default | compact markdown rendering). Results carry a session-stable ref.
  • image_search / news_search / video_search / music_search / paper_search — query (required) plus the shared optional args: engines, language, pageno, safesearch, max_results, detail, and time_range (all five support the freshness filter).
  • fetch_content — url (string, required): absolute http/https, or ref:N to cite a search result, max 2048 chars. max_chars (1000–200000, default MAX_CHARS 25000). offset (int ≥ 0): window start into the extracted content — continue from the returned nextOffset. outline: true adds headings ({text, offset, level}: markdown #-lines, [Page N] markers for PDFs) with offsets into the scanned content. section returns one heading region only — case-insensitive exact heading match, through the next same-or-higher-level heading — with offset/max_chars applying inside it. timeout_ms (max 120000). archive: true retries a dead link (404/410/5xx, unreachable, timed out) through the closest Internet Archive snapshot (result marked archived). Text PDFs are extracted per page ([Page N] sections, pages count in the output).
  • search_and_fetch — query (required) plus the search args and: fetch_top (1–5, default 3) fetches the top delivered results' full content; max_chars caps each page. Output: the search envelope plus pages[] (one entry per fetched page with content or error).
  • crawl_site — url (seed, required), max_pages (1–30, default 10). Follows same-origin links breadth-first (robots.txt honored best-effort) and returns a manifest with a ref per page; the extracted content is cached, so fetch_content ref:N reads it without re-fetching.
  • doctor — no arguments. Returns checks[] (id, ok, detail) covering the JSON API, /config, unresponsive engines and limiter state, plus a healthy verdict.
  • deep_search — query (required), max_iterations (1–4, default 2), sources_per_iteration (1–5, default 2), max_results. Returns a cited dossier (sources[] with refs, notes[] excerpts, optional synthesis). With io.modelcontextprotocol/tasks negotiated, returns a task handle to poll via tasks/get.
  • autocomplete — query (string, required): the prefix to complete, max 200 chars. Suggestions follow the instance's configured language.

Configuration

Env varDefaultPurpose
SEARXNG_URLhttp://localhost:8888Base URL of the SearXNG instance.
SEARXNG_URLSunsetOptional failover instances (comma-separated), tried in order after SEARXNG_URL on network errors, timeouts, 5xx, 429 and 403.
SEARXNG_CACHE_TTL_MS0 (off)Opt-in response cache TTL for instance-bound GETs (in-memory LRU, 128 entries). fetch_content is never cached.
SEARXNG_USERNAME / SEARXNG_PASSWORDunsetUsername and password for SearXNG basic auth (optional).
SEARXNG_TIMEOUT_MS10000Timeout for search API requests.
SEARXNG_HTML_FALLBACKfalseOpt-in: when the JSON API is disabled (403) or answers non-JSON, retry search against the instance's HTML UI and parse the page. Enable when targeting public instances behind a limiter that disable the JSON API.
SEARXNG_DEFAULT_LANGUAGEunsetDefault language for the search tools when a request omits it.
SEARXNG_DEFAULT_SAFESEARCHunsetDefault safesearch (0/1/2) when a request omits it; invalid values are ignored with a warning.
SEARXNG_MAX_RESULTSunsetCeiling on request max_results (int ≥ 1); larger requests clamp to it with a once-per-process warning.
SEARXNG_RERANK_BOOST_DOMAINSunsetComma-separated hostnames (suffix match) boosted by the search/search_and_fetch heuristic rerank.
SEARXNG_ARCHIVE_FALLBACKfalseOpt-in Wayback fallback: dead fetch_content links (404/410/5xx, unreachable, timed out) retry through the closest Internet Archive snapshot, still SSRF-guarded. Per-call override: archive: true.
SEARXNG_SYNTHESIS_URLunsetOpenAI-compatible chat-completions endpoint for deep_search synthesis (Ollama: http://localhost:11434/v1/chat/completions). Unset → dossier-only. Validated http/https; never logged.
SEARXNG_SYNTHESIS_MODELunsetModel name sent to the synthesis endpoint.
FETCH_TIMEOUT_MS15000Timeout for page fetches.
SHUTDOWN_TIMEOUT_MS5000Hard cap on graceful shutdown after SIGINT/SIGTERM (minimum 100).
MAX_CHARS25000Maximum characters returned per fetched page (per-call override: max_chars).
MAX_RESPONSE_BYTES5242880Maximum download size per fetch (5 MiB).
USER_AGENTsearxng-mcp-server/<version>User-Agent header sent by all tools.
ALLOW_PRIVATE_HOSTSfalseSet true/1/yes/on to permit private-network targets (defeats the SSRF guard — only for trusted networks).
SEARXNG_TRANSPORTstdioTransport: stdio (default) or http (Streamable HTTP, 2026-07-28 revision only).
HOST / PORT127.0.0.1 / 3000HTTP transport: bind address and port. Non-localhost binds require SEARXNG_AUTH_TOKEN (startup is refused otherwise).
SEARXNG_AUTH_TOKENunsetHTTP transport: require Authorization: Bearer <token> on every request (mandatory for non-localhost binds).
SEARXNG_ALLOWED_HOSTSlocalhost setHTTP transport: extra allowed Host header hostnames (comma-separated) — add yours behind a reverse proxy.
SEARXNG_ALLOWED_ORIGINSlocalhost setHTTP transport: extra allowed Origin header hostnames (comma-separated), for browser-based clients.

A --transport stdio|http CLI flag overrides SEARXNG_TRANSPORT; an invalid flag value fails startup instead of silently falling back.

Security

  • SSRF guard: fetch_content validates the URL and resolves DNS before connecting, rejecting private, loopback, link-local and other non-public ranges (IPv4 and IPv6), IP-literal tricks included. Every redirect hop is re-validated, https→http downgrades are refused, and the same guarded DNS lookup runs again at connect time (DNS-rebind protection). Opt out only with ALLOW_PRIVATE_HOSTS=true.
  • Prompt-injection mitigation: search output, fetched page content, crawl manifests and deep-search dossiers are wrapped in an untrusted-content banner; embedded closing markers and forged opening markers are neutralized. Error messages that reflect user-supplied URLs are sanitized identically. The MCP Apps gallery renders untrusted data only through safe DOM APIs (textContent / checked attributes), never HTML parsing.
  • Archive fallback is opt-in and guard-preserving: the snapshot URL re-enters the same SSRF-guarded pipeline, and policy refusals (private hosts, unsupported content types, scheme downgrades) never trigger the fallback.
  • Crawling is same-origin, page-capped, robots-aware and goes through the guarded fetcher for every page; the content store is bounded (256 pages).
  • Tasks (when negotiated) use unguessable UUIDv4 ids, immutable terminal states, bounded TTL'd stores and no tasks/list — one caller's tasks are never visible to another.
  • Secrets (SEARXNG_PASSWORD, SEARXNG_AUTH_TOKEN, SEARXNG_SYNTHESIS_URL credentials) are never logged; all MCP logs go to stderr, stdout is reserved for JSON-RPC. A W3C traceparent in a request's _meta is validated (strict lowercase format) before it propagates to outbound calls; invalid values are never forwarded.
  • Found a vulnerability? Please report it privately — do not open a public issue.

Troubleshooting

  • SearXNG returned 403: the JSON API is disabled — add json to search.formats in searxng/settings.yml and restart the stack, or set SEARXNG_HTML_FALLBACK=true to parse the HTML UI instead.
  • Could not reach SearXNG — the Docker stack is not running, or SEARXNG_URL is wrong in the client's env block.
  • npx fails to start the server — Node 22.19+ is required; check node -v.
  • Port 8888 already bound — change the compose port mapping and SEARXNG_URL to match.
  • HTTP: Unsupported protocol version — the endpoint serves the 2026-07-28 revision only; upgrade the client or enable version negotiation (see Streamable HTTP).
  • HTTP: failed to start … set SEARXNG_AUTH_TOKEN — the guard against unauthenticated non-localhost binds; set the token or bind to 127.0.0.1.
  • HTTP: 403 with a browser-based client — its Origin is not in the allowlist; add the hostname to SEARXNG_ALLOWED_ORIGINS.

Development

bash
pnpm test             # vitest unit testspnpm lint && pnpm lint:types && pnpm format:check   # oxlint + prettierpnpm typecheck        # tsc --noEmitpnpm build            # outputs dist/node scripts/e2e.mjs      # end-to-end over stdio against the local SearXNG stacknode scripts/e2e-http.mjs # same over the Streamable HTTP transport

Architecture and security rationale live in docs/design.md; adding a search category: the checklist in docs/extending.md. PRs are welcome — run the Development gate before submitting. Maintainer: @bumbaRasch.

License

MIT

来源：README.md，提交 519183d

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

3
  1. v1.0.1最新Oct 18, 2026
  2. v0.3.1Sep 20, 2026
  3. v0.1.1Sep 20, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分