searxng-mcp

Un servidor MCP para búsqueda web privada a través de una instancia autoalojada de SearXNG. Los resultados se reordenan con un modelo de ML local, el contenido completo de las páginas se obtiene mediante Firecrawl, y una instancia opcional de Ollama proporciona expansión de consultas y resúmenes sintetizados por LLM.

Diseñado para su uso con agentes de Claude Code y LibreChat que necesitan búsqueda web sin enviar consultas a una API de búsqueda de terceros.

Construido con Claude Code utilizando el flujo de trabajo multiagente de homelab-agent — la misma plataforma que usa searxng-mcp en producción para investigación asistida por IA.

Inicio rápido

Se requiere una instancia en ejecución de SearXNG. Se recomienda encarecidamente un backend de caché.

Stack mínimo — inicia un backend de caché Dragonfly/Valkey y ejecuta searxng-mcp:

docker compose -f docker-compose.example.yml up -d
SEARXNG_URL=http://localhost:8081 CACHE_URL=redis://localhost:6381 npx @tadmstr/searxng-mcp

Para una topología local completa que incluya Firecrawl, Crawl4AI, Ollama, Kiwix, el proxy de bloqueo de anuncios y NATS, consulta docker-compose.full.yml.

Related MCP server: searxng-mcp-bridge

Herramientas

Parámetros

category — general (por defecto), news, it, science

time_range — day, week, month, year — limita los resultados por fecha de publicación. Omitir para resultados de todos los tiempos.

fetch_count — número de mejores resultados reordenados para obtener su contenido completo (por defecto 1, máximo 3 para search_and_fetch; por defecto 3, máximo 5 para search_and_summarize).

domain_profile — aplica un perfil de filtro de dominio con nombre: homelab (muestra documentación autoalojada/Linux) o dev (muestra Stack Overflow, MDN, npm). Omitir para filtros predeterminados.

expand — cuando es true, reescribe la consulta mediante Ollama (OLLAMA_EXPAND_MODEL) antes de buscar para mejorar la recuperación. Requiere OLLAMA_URL. Por defecto, toma el valor de la variable de entorno EXPAND_QUERIES.

language — código de idioma BCP-47 (por ejemplo, en, de) o all para restringir a un idioma específico. Omitir para usar el valor predeterminado de la instancia de SearXNG. Disponible en search, search_and_fetch y search_and_summarize.

engines — nombres de motores de SearXNG separados por comas para restringir la búsqueda (por ejemplo, google,duckduckgo). Se reenvían tal cual; los motores desconocidos/deshabilitados degradan a menos resultados en lugar de generar errores. Disponible en las tres herramientas de búsqueda.

site — restringe los resultados a un dominio o una lista (por ejemplo, github.com o ["github.com", "gitlab.com"]). Se aplica de la mejor manera posible como operador de consulta site: — la mayoría de los motores (Google, Bing, DDG, Brave) lo respetan, algunos lo ignoran. Disponible en las tres herramientas de búsqueda.

max_tokens (fetch_url) — presupuesto aproximado de tokens para el contenido devuelto (caracteres ≈ tokens × 4). Omitir para el valor predeterminado de ~2,000 tokens / 8,000 caracteres; máximo 10,000 tokens.

target_selector (fetch_url) — selector CSS para limitar la extracción a un elemento específico (por ejemplo, article, main .content). Es respetado de forma nativa por Firecrawl/Crawl4AI y se aplica en el lado del cliente en el nivel HTTP sin procesar; se ignora en las rutas rápidas y cuando no coincide con nada.

wait_for_selector (fetch_url) — selector CSS para esperar antes de extraer, para páginas renderizadas con JS. Es respetado por los niveles de renderizado (Firecrawl/Crawl4AI); se ignora en HTTP sin procesar (sin JS).

Arquitectura

MCP client (stdio)
      │
      ▼
  searxng-mcp ──────────────→ cache ($CACHE_URL)           → result cache (search 1h, fetch 24h, crawl 6h)
      │
      ├── expand (optional) →  Ollama ($OLLAMA_URL)        → rewritten query (qwen3:4b)
      ├── search ───────────→ SearXNG ($SEARXNG_URL)      → raw results
      ├── rerank ───────────→ Reranker ($RERANKER_URL)    → ranked results
      │                       (fallback: SearXNG order if reranker unavailable)
      ├── fetch content ────┬→ GitHub API (github.com)    → markdown
      │                     ├→ Kiwix ($KIWIX_URL)         → ZIM content (Wikipedia/SO/Arch Wiki, fast path)
      │                     ├→ Hister ($HISTER_URL)       → browsing-history index (login-walled/JS-heavy fast path)
      │                     ├→ Firecrawl ($FIRECRAWL_URL) → page markdown (tier 1)
      │                     ├→ Crawl4AI ($CRAWL4AI_URL)  → page markdown (tier 2, optional; via $ADBLOCK_PROXY_URL if set)
      │                     ├→ Raw HTTP + Readability     → page markdown (tier 3 fallback; via $ADBLOCK_PROXY_URL if set)
      │                     └→ Wayback Machine (opt-in)  → archived page markdown (tier 4, $WAYBACK_ENABLED)
      ├── crawl_site ───────┬→ Firecrawl crawl           → page manifest (phase 1)
      │                     ├→ Sitemap parsing           → page manifest (phase 2 fallback, fast-xml-parser)
      │                     └→ BFS crawl (opt-in)        → page manifest (phase 3, $CRAWL_BFS_ENABLED)
      └── summarize (opt.) →  Ollama ($OLLAMA_URL)        → synthesized summary ($OLLAMA_SUMMARIZE_MODEL)

flowchart TD
    entry["fetchPage(url)"]
    cache{"Valkey cache hit?"}
    cached["→ return cached { title, url, text }"]
    github{"GitHub host?\ngithub.com · raw · api"}
    gh_fetch["GitHub API / raw.githubusercontent.com / api.github.com\n→ return"]
    llms{"llms.txt domain?"}
    llms_fetch["Probe /llms-full.txt\nextract matching section\n→ return"]
    kiwix{"Kiwix host?\nKIWIX_URL set"}
    kiwix_fetch["Local Kiwix ZIM\nWikipedia · Stack Overflow · Arch Wiki\n→ cache + return"]
    pdf{".pdf URL?"}
    robots["robots.txt pre-check — tiers 1–3\ndisallowed → RobotsDisallowedError (cached 24h)"]
    tier_skip(["Per-domain tier skip\nsuccess rate <30% over ≥10 tries\nor tier_skip operator override"])
    t1["Tier 1 — Firecrawl\n$FIRECRAWL_URL"]
    t2["Tier 2 — Crawl4AI\n$CRAWL4AI_URL · optional\nadblock proxy if $ADBLOCK_PROXY_URL"]
    t3["Tier 3 — Raw HTTP + Readability\nfallback: raw HTML slice\nadblock proxy if $ADBLOCK_PROXY_URL"]
    t4["Tier 4 — Wayback Machine CDX API\narchived snapshot · WAYBACK_ENABLED=true"]
    post["Post-extraction\nJSON-LD Article · title cascade\nog:title → twitter:title → title → h1 → URL"]
    result["→ return { title, url, text }"]

    entry --> cache
    cache -->|hit| cached
    cache -->|miss| github
    github -->|yes| gh_fetch
    github -->|no| llms
    llms -->|yes| llms_fetch
    llms -->|no| kiwix
    kiwix -->|yes| kiwix_fetch
    kiwix -->|no| pdf
    pdf -->|"yes — skip tier 1"| t2
    pdf -->|no| robots
    robots --> tier_skip
    tier_skip --> t1
    t1 -->|success| post
    t1 -->|"empty / error"| t2
    t2 -->|success| post
    t2 -->|"empty / error"| t3
    t3 -->|success| post
    t3 -->|"empty / error"| t4
    t4 -->|success| result
    post --> result

    style entry fill:#ffffff,stroke:#333333,color:#000000
    style cache fill:#ffffff,stroke:#333333,color:#000000
    style cached fill:#ffffff,stroke:#333333,color:#000000
    style github fill:#dae8fc,stroke:#6c8ebf,color:#000000
    style gh_fetch fill:#dae8fc,stroke:#6c8ebf,color:#000000
    style llms fill:#dae8fc,stroke:#6c8ebf,color:#000000
    style llms_fetch fill:#dae8fc,stroke:#6c8ebf,color:#000000
    style kiwix fill:#fff9c4,stroke:#b8860b,color:#000000
    style kiwix_fetch fill:#fff9c4,stroke:#b8860b,color:#000000
    style pdf fill:#ffffff,stroke:#333333,color:#000000
    style robots fill:#ffffff,stroke:#333333,color:#000000
    style tier_skip fill:#f5f5f5,stroke:#666666,color:#000000
    style t1 fill:#d5e8d4,stroke:#5a8a4a,color:#000000
    style t2 fill:#d5e8d4,stroke:#5a8a4a,color:#000000
    style t3 fill:#d5e8d4,stroke:#5a8a4a,color:#000000
    style t4 fill:#f8cecc,stroke:#a03030,color:#000000
    style post fill:#e1d5e7,stroke:#7a5a8a,color:#000000
    style result fill:#ffffff,stroke:#333333,color:#000000

SearXNG y Firecrawl son obligatorios. Crawl4AI, Valkey, Ollama, Kiwix y el reordenador son opcionales: el servidor se degrada con elegancia cuando cualquiera de ellos no está disponible.

Bloqueo de anuncios

searxng-mcp utiliza dos sidecars independientes de bloqueo de anuncios, uno por grupo de niveles de obtención:

Nivel 1 — Bloqueo de anuncios de Puppeteer

El servicio firecrawl-puppeteer utilizado por Firecrawl ejecuta una imagen personalizada (docker/puppeteer-adblock/) que superpone @ghostery/adblocker-puppeteer sobre el trieve/puppeteer-service-ts ascendente. EasyList + EasyPrivacy se cargan al inicio y se actualizan cada 168 horas; el bloqueador se aplica a cada página que Firecrawl crea. Acelera la obtención de sitios con muchos anuncios y reduce el tamaño del DOM renderizado.

Variables de entorno:

La imagen base está fijada por digest SHA256. Para implementar un cambio, reconstruye y reinicia el servicio:

docker compose -f ~/docker/firecrawl-simple/docker-compose.yml up -d --build firecrawl-puppeteer

Omisión por dominio: domains.json reserva una ranura adblock_skip para futuras anulaciones del operador. El cableado aún no está implementado: requeriría que Firecrawl reenvíe un encabezado personalizado al servicio de puppeteer, lo cual no es parte de su API actual. Se rastrea como elemento de expansión de alcance I.

Niveles 2+3 — Proxy de bloqueo de anuncios

Establece ADBLOCK_PROXY_URL (por ejemplo, http://adblock-proxy:8118) para enrutar las solicitudes de Crawl4AI y de obtención sin procesar de Node a través de un proxy de reenvío HTTP que filtra solicitudes de anuncios y rastreadores. Los túneles CONNECT de HTTPS se pasan sin modificar (sin MITM), por lo que el filtrado se aplica solo a dominios de anuncios de HTTP simple. El enganche de puppeteer del nivel 1 ya maneja el filtrado HTTPS completo para ese nivel; el proxy cubre lo que se filtra en los niveles 2 y 3.

Consulta docker/adblock-proxy/ para la definición del servicio, las opciones de configuración y las instrucciones de implementación (incluidas en docker-compose.full.yml).

Enrutamiento de niveles basado en datos

Antes de invocar la cascada de obtención, searxng-mcp lee el tier_stats_30d del dominio (consulta base de datos de capacidades de dominio) y omite cualquier nivel con una tasa de éxito inferior al 30% en al menos 10 intentos. Los dominios en frío (<10 intentos) mantienen la cascada predeterminada. Cada omisión emite un evento NATS searxng.fetch.tier.skipped con reason: low_success_rate e incrementa searxng_fetch_total{outcome=skipped}.

Anulación del operador. Agrega un mapa tier_skip a domains.json para forzar la omisión de niveles independientemente de las estadísticas:

{
  "tier_skip": {
    "example-bot-blocked.com": ["tier1"],
    "another-site.example": ["tier1", "tier2"]
  }
}

Las claves de tier_skip pueden ser dominios simples (example.com coincide con el dominio y todos los subdominios) o dominio + prefijo de ruta (example.com/api/). El archivo se recarga en caliente: no se necesita reinicio. Las anulaciones manuales emiten reason: operator_override.

Ruta rápida de tipo de contenido

Una URL que sirve contenido estructurado no HTML — application/json, cualquier *+json, XML, YAML, TOML, CSV o text/plain — se detecta mediante una sonda HEAD y se enruta directamente al nivel HTTP sin procesar en lugar de a la cascada completa de Firecrawl/Crawl4AI. El JSON se devuelve con formato bonito dentro de un bloque de código cercado. Anteriormente, pedir a un navegador sin interfaz que renderizara una respuesta de API JSON o un recurso CDN devolvía markdown vacío, por lo que los endpoints de API y CDN (registry.npmjs.org, api.osv.dev, cdn.jsdelivr.net, …) simplemente fallaban.

Garantías:

• La sonda es fail-open. Un host inalcanzable, un servidor que rechaza HEAD o una cabecera Content-Type ilegible o no analizable caen todos a la cascada normal sin cambios.

• application/xhtml+xml se excluye deliberadamente: eso es marcado para un navegador, no datos estructurados.

• El HTML que un servidor etiqueta erróneamente como text/plain se sigue analizando como HTML, no se vuelca como un bloque de texto sin procesar.

Base de datos de capacidades de dominio

Cada búsqueda registra lo que searxng-mcp aprende sobre el dominio de destino en Valkey bajo domain:<hostname> (TTL de 90 días, schema_version 5). Capturado por registro:

• tier_stats_30d.{tier1,tier2,tier3,tier4,github}.{attempts, ok, fail, last_fail_reason, window_start_ms} — tasa de éxito de búsqueda por nivel en una ventana móvil de 30 días. El corte se aplica en tiempo de lectura, compartido por las decisiones de enrutamiento de nivel y los informes de domain_stats, de modo que ambos no pueden discrepar: un dominio buscado una vez y luego dejado inactivo informa una ventana genuinamente vacía en lugar de números obsoletos que sobreviven hasta la siguiente escritura. La ranura tier4 (Wayback Machine) se registra solo cuando WAYBACK_ENABLED=true. La ranura github registra la ruta rápida de GitHub (raw.githubusercontent.com / api.github.com / búsquedas de README de github.com), que omite la cascada de niveles pero aún se rastrea aquí. Un aumento de schema_version reconstruye los registros existentes desde cero: las ventanas acumuladas para dominios actualmente inactivos se descartan (con precedente en los aumentos 1→2, 2→3, 3→4, 4→5).

• capabilities.metadata_fetch.{attempts, ok, fail, last_fail_reason} — éxito/fracaso de la búsqueda del canal secundario de metadatos (fetchRawHtmlForMetadata, utilizado para el muestreo de JSON-LD/og:title). Se rastrea por separado de tier_stats_30d porque responde a "¿es alcanzable este dominio?", no a "¿la entrega de contenido completo tuvo éxito?".

• capabilities.seen_in_search.{count, last_seen_ms} — con qué frecuencia aparece el dominio en los resultados de search. Escrito de forma fire-and-forget por searxSearch() en cada ruta de retorno (incluidos los aciertos de caché) sin realizar una búsqueda, de modo que un dominio puede rastrearse antes de que se busque.

• capabilities.robots_txt.{present, fetched, allows_us} — presencia de robots.txt y si nos permite

• capabilities.llms_full_txt.{present, size_bytes, last_checked} — si el dominio sirve /llms-full.txt

• capabilities.json_ld_article.{sampled, present, last_sampled_at} — si la página lleva JSON-LD de esquema Article (Schema.org Article/NewsArticle/BlogPosting/TechArticle y subtipos como ScholarlyArticle/OpinionNewsArticle/LiveBlogPosting, coincididos por nombre simple o @type totalmente calificado https://schema.org/...), independientemente de si ese esquema tenía texto de cuerpo extraíble — muchos sitios publican JSON-LD de titular/metadatos sin articleBody, lo cual es una preocupación distinta de que la post-extracción realmente lo use.

• capabilities.og_title.{sampled, present, last_sampled_at} — lo mismo para <meta property="og:title">

• preferred_strategy — actualmente se establece en llms_full_txt cuando una sonda presente aterriza; las fases futuras usarán esto para omitir la cascada de niveles

Inspeccione un registro con el CLI incluido, o consúltelo desde un agente mediante la herramienta domain_stats (de un solo dominio o agregada; consulte Herramientas):

pnpm dump-domain docs.anthropic.com

dump-domain distingue una ventana que ha expirado de un nivel que no tiene datos en absoluto, en lugar de mostrar ambos de la misma manera.

Las actualizaciones concurrentes para el mismo hostname (los registradores de intento de nivel, sonda de robots y muestra post-extracción que se disparan en paralelo durante una búsqueda) se serializan mediante un compare-and-set Lua del lado del servidor, junto con una cola por clave en el proceso que elimina la contención entre los propios escritores de un solo proceso, de modo que el CAS solo tiene que arbitrar escrituras genuinamente concurrentes entre procesos. Las versiones anteriores a v3.17.0 usaban una lectura-modificación-escritura WATCH/MULTI/EXEC contra una conexión compartida, que en realidad no serializa escritores concurrentes — los datos recopilados antes de v3.17.0 eran sustancialmente incompletos como resultado. La actualización descarta las estadísticas de nivel existentes mediante el aumento de esquema; espere que domain_stats lea casi vacío inmediatamente después de actualizar y se rellene en los días siguientes.

Persistencia de la base de datos de dominios

La base de datos de dominios vive solo en Valkey bajo un TTL de 90 días y ventanas móviles de 30 días, por lo que un vaciado de caché o la expiración del TTL borra el aprendizaje de capacidades que es costoso de readquirir. Dos CLIs lo hacen duradero:

pnpm domain-db-maintenance   # SCAN all domain:* records → write a dated JSON snapshot (+ prune) and emit OTel gauges
pnpm restore-domain-db       # re-seed the domain-db from the newest snapshot after a flush

• domain-db-maintenance es un trabajo independiente (ejecútelo en un horario mediante cron o un reinicio cron de PM2 — no como un temporizador en el proceso, ya que searxng-mcp se ejecuta como varios hijos stdio concurrentes por agente que cada uno lo dispararía). Un SCAN acotado alimenta ambas salidas: una instantánea fechada duradera y, cuando OTEL_EXPORTER_OTLP_ENDPOINT está establecido, medidores (searxng_domains_tracked, searxng_domains_failing, searxng_domain_tier_success_ratio{tier}) forzados a vaciarse antes de salir.

• restore-domain-db re-siembra solo las claves que faltan o cuyo registro vivo es estrictamente más antiguo que la instantánea (compara last_fetch) — nunca sobrescribe un registro vivo más reciente o igual, por lo que es seguro ejecutarlo contra un Valkey vivo y parcialmente poblado (por ejemplo, en una secuencia de arranque de servicio para recuperación automática de vaciado).

Ruta rápida de llms.txt

Para dominios de documentación en lista blanca en domains.json (array llms_txt), fetchPage intenta <origin>/llms-full.txt primero y extrae la sección que coincide con la URL solicitada antes de invocar cualquier nivel. Esto evita ejecutar puppeteer contra sitios de documentación bien instrumentados y devuelve directamente una sección de markdown limpia. Los resultados de la sonda y el cuerpo completo se almacenan en caché en Valkey (llms:<origin>:full, 24 h / 7 d para presente/ausente). Lista blanca predeterminada: docs.anthropic.com, docs.openai.com, docs.stripe.com, docs.crawl4ai.com, docs.firecrawl.dev, docs.cursor.com. Extienda editando domains.json — el archivo se recarga en caliente.

Ruta rápida de Kiwix

Cuando KIWIX_URL está establecido, las solicitudes de búsqueda para hosts conocidos con capacidad offline se interceptan antes de la cascada de Firecrawl/Crawl4AI y se sirven desde el archivo ZIM local de Kiwix. Esto elimina la tasa de fallo del 100% del nivel 1 para sitios como Wikipedia (que bloquea los raspadores sin interfaz) y devuelve contenido limpio y legible con cero tráfico de red externo.

Hosts admitidos y libros ZIM (kiwix-serve debe ejecutarse con --nodatealiases / -z):

La ruta de Kiwix se ejecuta después de la ruta rápida de llms-txt y antes de la puerta de robots. Si la solicitud de Kiwix falla o devuelve vacío, la cascada de niveles completa se ejecuta normalmente. Cuando KIWIX_URL no está establecido, la característica añade cero sobrecarga — isKiwixHost() devuelve false inmediatamente.

Establezca KIWIX_URL a su URL base de kiwix-serve (por ejemplo, http://localhost:8292).

Rutas rápidas de YouTube y Reddit

fetch_url reconoce URLs de videos de YouTube (youtube.com, youtu.be) y URLs de hilos de Reddit y puede servirlas directamente en lugar de raspar la página renderizada:

• YouTube — extrae la pista de subtítulos del video de la página de visualización y devuelve la transcripción. Habilitado por YOUTUBE_TRANSCRIPT_ENABLED (activado por defecto).

• Reddit — obtiene la vista pública .json y devuelve la publicación más los comentarios principales en la forma estándar {title, url, text}; cae en caso de HTTP 429. Habilitado por REDDIT_FASTPATH_ENABLED (activado por defecto).

Ambos dependen de endpoints no oficiales y no documentados (la API timedtext de YouTube, el .json de Reddit) — de mejor esfuerzo sin SLA; cualquiera puede romperse ante un cambio ascendente, de ahí los interruptores de apagado. Ante cualquier fallo, la solicitud cae a la cascada de niveles normal (que aún puede obtener el título/descripción de una página de YouTube).

robots.txt: ambos endpoints están deshabilitados por los robots.txt de los sitios (Reddit lo deshabilita todo; YouTube deshabilita /api/, donde vive la transcripción). Por defecto, estas rutas rápidas respetan eso y permanecen inactivas, cayendo a la cascada. En su propia instancia puede optar por la búsqueda directa con YOUTUBE_IGNORE_ROBOTS=true / REDDIT_IGNORE_ROBOTS=true.

Rastreo de sitios

crawl_site rastrea un sitio completo y devuelve un manifiesto de URL/título/fragmento para cada página encontrada. Utiliza una cascada de estrategias de tres fases:

1. Rastreo de Firecrawl — envía un trabajo de rastreo a Firecrawl (endpoint /crawl), sondea hasta que se complete y devuelve la lista completa de páginas. Controlado por FIRECRAWL_CRAWL_POLL_INTERVAL_MS y FIRECRAWL_CRAWL_MAX_WAIT_MS.

2. Análisis de sitemap — si Firecrawl falla o devuelve vacío, obtiene /sitemap.xml (y sitemaps enlazados) y extrae URLs con títulos/fragmentos. Utiliza fast-xml-parser para el análisis XML del sitemap.

3. Rastreo BFS (opt-in) — si el análisis del sitemap también falla, realiza un rastreo en amplitud comenzando desde la URL dada hasta CRAWL_BFS_MAX_DEPTH saltos de enlace. Solo se ejecuta cuando CRAWL_BFS_ENABLED=true o el parámetro de herramienta bfs es true.

El contenido completo de la página obtenido durante el rastreo se almacena en caché en Valkey (TTL: CRAWL_MANIFEST_TTL_SECONDS, predeterminado 6 horas). Las llamadas posteriores a fetch_url para cualquier URL en el manifiesto devuelven inmediatamente desde la caché — cero sobrecarga de búsqueda para lecturas de seguimiento.

La caché del manifiesto se puede limpiar con clear_cache(target="crawl").

Respaldo de Wayback Machine

Cuando WAYBACK_ENABLED=true, un cuarto nivel consulta la API CDX de Wayback Machine para obtener una instantánea archivada cuando fallan los tres niveles principales. El contenido devuelto se prefija con una cabecera de procedencia ([Instantánea archivada – <timestamp> – <original_url>]) para que los llamadores sepan que el contenido puede no reflejar el estado actual de la página.

Calidad de búsqueda

Después de que cualquier nivel devuelva contenido con HTML sin procesar, un pase posterior a la extracción mejora la calidad del título y del cuerpo:

• Extracción de artículo JSON-LD — los bloques de Schema.org Article / NewsArticle / BlogPosting / TechArticle suministran headline y articleBody más limpios que el raspado de cromo del nivel 1 (con límite de tamaño de 1 MB por etiqueta de script).

• Cascada de títulos — retrocede a través de og:title → twitter:title → <title> (con eliminación de sufijo de editor) → primer <h1> → URL.

• Comparación de legibilidad del nivel 2 — cuando Crawl4AI devuelve markdown, JSDOM+Readability también se ejecuta sobre su HTML sin procesar y se prefiere cuando su texto es más largo (o incondicionalmente cuando Crawl4AI devuelve menos de 500 caracteres).

Resiliencia

• La caché nunca bloquea una búsqueda. El cliente de Valkey está limitado por CACHE_COMMAND_TIMEOUT_MS/CACHE_CONNECT_TIMEOUT_MS/CACHE_MAX_RETRIES_PER_REQUEST (ver Configuración). Un backend de caché atascado o con picos de CPU ahora rechaza el comando en lugar de bloquearse para siempre — el manejo existente de fallo suave degrada ese rechazo a un fallo de caché (servir en vivo) en lugar de lanzar una excepción. Los fallos de conexión de caché, errores de cliente y errores por comando emiten una línea de stderr limitada [searxng-mcp] (deduplicada por clave, de modo que una interrupción sostenida deja una miga de pan periódica, no una inundación) — stderr es el único sumidero de telemetría conectado en el proceso PM2 desplegado.

• Manejadores de caída de proceso — uncaughtException registra y luego sale con código 1 (reinicio limpio de PM2); unhandledRejection registra y continúa en lugar de colapsar el proceso compartido silenciosamente.

• Advertencias de degradación elegante — el respaldo del reranker y los respaldos de expansión y resumen de Ollama/LLM emiten una línea de stderr limitada cada uno cuando degradan silenciosamente la calidad (reranker no disponible, backend LLM inalcanzable).

• La versión tiene una única fuente desde package.json en tiempo de ejecución (src/version.ts) — la versión de McpServer, la versión del tracer/medidor de OTel y el USER_AGENT saliente la siguen, por lo que no pueden desviarse de forma independiente.

Observabilidad (opt-in)

El rastreo, las métricas y la publicación de eventos son completamente opt-in — sin ninguna de las variables de entorno siguientes configuradas, el servidor tiene cero sobrecarga de observabilidad y nunca carga los paquetes de OpenTelemetry o NATS en tiempo de ejecución.

OpenTelemetry (trazas + métricas) — establece OTEL_EXPORTER_OTLP_ENDPOINT al endpoint HTTP de tu colector y el servidor emite:

• Spans (por solicitud): tool.<name> → expand_query? → searxng_request → rerank → fetch (×N) → tier1_firecrawl | tier2_crawl4ai | tier3_rawfetch → post_extract; además summarize_llm para search_and_summarize.

• Contadores: searxng_search_total{profile, expand}, searxng_fetch_total{tier, outcome}, searxng_cache_total{namespace, outcome}, searxng_errors_total{stage, error_type}.

• Histogramas: searxng_search_duration_seconds{profile}, searxng_fetch_duration_seconds{tier, outcome}.

Se aplican las variables de entorno estándar de OTEL (OTEL_SERVICE_NAME por defecto es searxng-mcp).

Eventos NATS — establece NATS_URL (por ejemplo, nats://localhost:4222) y el servidor publica un evento estructurado en cada búsqueda, captura, acierto/fallo de caché, omisión de robots y error. Autentica mediante NATS_CREDS (un archivo de credenciales JWT) o NATS_USER/NATS_PASSWORD (nombre de usuario/contraseña bcrypt) — la autenticación por archivo de credenciales gana si ambos están configurados. Asuntos:

Cada sobre incluye request_id y (cuando OTel está habilitado) trace_id para que los suscriptores puedan unir los dos flujos. El prefijo del asunto se puede sobrescribir mediante NATS_SUBJECT_PREFIX. Las consultas de búsqueda fluyen a través de eventos search.* — los consumidores posteriores son responsables de cualquier limpieza de PII.

Cortesía

• User-Agent honesto — las solicitudes salientes se identifican como searxng-mcp/<version> (+https://github.com/TadMSTR/searxng-mcp; investigación personal).

• Cumplimiento de robots.txt — /robots.txt se obtiene una vez por origen y se almacena en caché durante 24 horas en Valkey bajo robots:<origin>. Las rutas no permitidas se omiten antes de que se ejecute cualquier nivel y se registran como skipped_robots url=… reason=….

Transporte

stdio (predeterminado) — compatible con el plugin MCP de Claude Code y la configuración stdio de LibreChat.

HTTP — establece SEARXNG_MCP_TRANSPORT=http para ejecutarse como un servidor HTTP/SSE compartido adecuado para despliegues multi-cliente o configuraciones basadas en Docker. Se vincula a SEARXNG_MCP_HOST:SEARXNG_MCP_PORT (por defecto 127.0.0.1:3001):

SEARXNG_MCP_TRANSPORT=http SEARXNG_MCP_PORT=3001 npx @tadmstr/searxng-mcp

Registra con Claude Code contra un servidor HTTP:

claude mcp add-json searxng --scope user '{
  "type": "http",
  "url": "http://localhost:3001/mcp"
}'

Las sesiones se identifican mediante el encabezado Mcp-Session-Id, por lo que múltiples clientes pueden conectarse al mismo proceso compartido de forma concurrente. Las sesiones inactivas se eliminan después de HTTP_SESSION_IDLE_TIMEOUT_MS y se limitan estrictamente a HTTP_MAX_SESSIONS — ver Configuración.

Autenticación del transporte HTTP

El transporte HTTP está sin autenticación por defecto, lo cual es seguro solo porque se vincula a 127.0.0.1 por defecto. Si cambias SEARXNG_MCP_HOST a cualquier otra cosa — incluido 0.0.0.0, que es lo que requiere ejecutar en un contenedor — establece también SEARXNG_MCP_AUTH_TOKEN:

SEARXNG_MCP_AUTH_TOKEN=$(openssl rand -hex 32)

Cuando está configurado, cada solicitud excepto GET /health debe llevar el token como credencial de portador RFC 6750:

Authorization: Bearer <token>

Cualquier otra cosa — sin encabezado, un esquema diferente, un token incorrecto — recibe 401 con WWW-Authenticate: Bearer y un cuerpo de error JSON-RPC. La respuesta es idéntica en los tres casos y nunca repite la credencial presentada. Los tokens se comparan como resúmenes SHA-256, por lo que la comparación es de tiempo constante y no filtra información de longitud.

Registrar un servidor autenticado con Claude Code:

claude mcp add-json searxng --scope user '{
  "type": "http",
  "url": "http://localhost:3001/mcp",
  "headers": {"Authorization": "Bearer <token>"}
}'

Dejar la variable sin configurar preserva exactamente el comportamiento anterior, por lo que los usuarios de stdio y los despliegues HTTP existentes vinculados a loopback no necesitan cambios. No hay un modelo de autorización por llamador — un solo token autentica el acceso al servidor, no una identidad de cliente particular. Al inicio, un enlace no-loopback sin token registra una advertencia.

GET /health está deliberadamente exento de la verificación. Es el healthcheck del contenedor y la sonda de liveness de monitoreo, no toma entrada, y su respuesta (status, cache, sessions) no lleva secretos.

GET /health — sonda de liveness sin autenticación, vinculada a localhost junto al endpoint MCP. Hace ping a Valkey a través del tiempo de espera de comando de caché limitado (para que la verificación en sí nunca se bloquee) y devuelve:

{"status": "ok", "cache": "up", "sessions": 3}

o, cuando el backend de caché es inalcanzable:

{"status": "degraded", "cache": "degraded", "sessions": 3}

sessions es el recuento de sesiones HTTP en vivo. Útil para el monitoreo de administradores de sistemas para detectar una caché degradada desde el lado MCP sin instrumentar directamente el backend de caché.

Requisitos previos

• Node.js 20+

• pnpm (o npm)

• Una instancia de SearXNG en ejecución

• Una instancia de Firecrawl en ejecución

• Un reranker en ejecución que exponga un endpoint /v1/rerank compatible con Jina (opcional)

• Una instancia de Valkey o compatible con Redis en ejecución (opcional, para caché de resultados)

• Una instancia de Ollama en ejecución con qwen3:4b y/o qwen3:14b descargados (opcional, para expansión de consultas y resumen)

SearXNG

SearXNG debe tener habilitado el formato de salida JSON. En settings.yml:

search:
  formats:
    - html
    - json

Reranker

El reranker debe exponer un endpoint /v1/rerank compatible con Jina. Un envoltorio ligero de FlashRank funciona bien — ver la referencia docker/reranker/ en homelab-agent.

Firecrawl

Cualquier instancia compatible con Firecrawl funciona. El despliegue local firecrawl-simple es suficiente. Establece FIRECRAWL_API_KEY si tu instancia requiere autenticación (por defecto es placeholder-local para despliegues locales que omiten la autenticación).

Crawl4AI

Crawl4AI es un respaldo de captura de segundo nivel opcional que se usa cuando Firecrawl devuelve contenido vacío (páginas bloqueadas por bots, sitios con mucho JavaScript). Establece CRAWL4AI_URL para habilitarlo. Si no está configurado, la cascada salta a la captura HTTP cruda.

docker run -d -p 11235:11235 unclecode/crawl4ai:0.8.6

Si tu instancia requiere autenticación por token de API, establece CRAWL4AI_API_TOKEN.

En la ruta search_and_summarize, las solicitudes de Crawl4AI usan fit_markdown para la extracción de contenido filtrado por ruido. Otros llamadores (search_and_fetch, fetch_url) usan raw_markdown.

Kiwix (opcional)

kiwix-serve sirve archivos ZIM sobre HTTP. Descarga los archivos ZIM requeridos y ejecuta kiwix-serve con --nodatealiases (-z) para que los nombres de los libros sean estables:

kiwix-serve --port 8292 --nodatealiases /path/to/zims/

Archivos ZIM requeridos para cada host compatible:

• Wikipedia: wikipedia_en_all_mini (o maxi)

• Stack Overflow: stackoverflow.com_en_all

• Arch Wiki: archlinux_en_all_maxi

Los archivos ZIM se pueden descargar desde library.kiwix.org.

Hister (opcional)

Hister es un índice de historial de navegación poblado por una extensión de Firefox. Cuando HISTER_URL está configurado, fetchPage verifica el índice de historial antes de invocar la cascada de niveles — útil para páginas con muro de inicio de sesión y con mucho JavaScript donde los raspadores fallan.

Establece HISTER_URL a la URL base de tu instancia de Hister y HISTER_TOKEN si se requiere autenticación por token de portador.

Valkey / Redis

Cualquier instancia compatible con Redis. Se recomienda Valkey. Los resultados de búsqueda se almacenan en caché durante 1 hora; las páginas capturadas durante 24 horas. Si no está disponible, el servidor opera sin caché.

Ollama

Requerido para expand y search_and_summarize. Descarga los modelos requeridos:

ollama pull qwen3:4b   # query expansion
ollama pull qwen3:14b  # summarization

El comportamiento de think: false se maneja automáticamente — no se necesita configuración adicional de Ollama.

Configuración

Todas las URLs de servicios son configurables mediante variables de entorno.

Instalación

npm (recomendado)

npm install -g @tadmstr/searxng-mcp

O ejecútalo directamente con npx:

npx @tadmstr/searxng-mcp

Desde el código fuente

git clone https://github.com/TadMSTR/searxng-mcp.git
cd searxng-mcp
pnpm install
pnpm build

Salida: build/src/index.js

Configuración del cliente MCP

Claude Code (CLI)

El enfoque recomendado usa claude mcp add-json para registrar el servidor con soporte completo de variables de entorno:

claude mcp add-json searxng --scope user '{
  "command": "npx",
  "args": ["-y", "@tadmstr/searxng-mcp"],
  "env": {
    "SEARXNG_URL": "http://localhost:8081",
    "FIRECRAWL_URL": "http://localhost:3002",
    "RERANKER_URL": "http://localhost:8787",
    "OLLAMA_URL": "http://localhost:11434",
    "CACHE_URL": "redis://localhost:6379",
    "CACHE_TTL_SECONDS": "3600",
    "FETCH_CACHE_TTL_SECONDS": "86400",
    "EXPAND_QUERIES": "false",
    "CRAWL4AI_URL": "http://localhost:11235"
  }
}'

Esto escribe en ~/.claude.json. No agregues searxng a ~/.claude/settings.json — ese archivo no se usa para la inyección de variables de entorno MCP en Claude Code.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "@tadmstr/searxng-mcp"],
      "env": {
        "SEARXNG_URL": "http://localhost:8081",
        "FIRECRAWL_URL": "http://localhost:3002",
        "RERANKER_URL": "http://localhost:8787",
        "OLLAMA_URL": "http://localhost:11434",
        "CACHE_URL": "redis://localhost:6379",
        "CRAWL4AI_URL": "http://localhost:11235"
      }
    }
  }
}

LibreChat (librechat.yaml)

mcpServers:
  searxng:
    type: stdio
    command: node
    args:
      - /path/to/searxng-mcp/build/src/index.js
    env:
      SEARXNG_URL: http://localhost:8081
      FIRECRAWL_URL: http://localhost:3002
      RERANKER_URL: http://localhost:8787
      OLLAMA_URL: http://localhost:11434
      CACHE_URL: redis://localhost:6379
      CRAWL4AI_URL: http://localhost:11235

URLs de GitHub

Las URLs de GitHub se manejan de forma nativa sin Firecrawl. githubFetch despacha según el nombre de host:

• Raíz del repositorio (github.com/owner/repo) — obtiene el README mediante la API de GitHub

• Blob de archivo (github.com/owner/repo/blob/branch/path/to/file) — reescribe y obtiene el contenido sin procesar de raw.githubusercontent.com

• Archivo sin procesar (raw.githubusercontent.com/...) — se obtiene directamente tal cual

• API (api.github.com/...) — respuesta decodificada (campos content en base64) o impresa de forma legible como JSON

Las URLs directas de raw.githubusercontent.com y api.github.com anteriormente coincidían solo con github.com y caían en la cascada de niveles de extracción de HTML, que no puede renderizar un archivo de texto sin procesar ni una respuesta JSON simple — fallaban el 100% de las veces. Ahora toman la ruta rápida de GitHub.

Las solicitudes no autenticadas están limitadas a 60/hora. Establece GITHUB_TOKEN para elevarlo a 5,000/hora.

Seguridad

Seguridad de URLs (SSRF)

Cada solicitud saliente a una URL influenciada por el llamador o descubierta — el nivel de HTTP sin procesar, las sondas de robots.txt / llms.txt / Wayback / sitemap, la obtención de enlaces del rastreo BFS y la ruta rápida de GitHub — está protegida de dos maneras:

1. Verificación de cadena (assertPublicUrl) — rechaza URLs que no sean HTTP(S) y literales de IP privadas/internas: RFC1918 (10.x, 192.168.x, 172.16–31.x), loopback (127.x, ::1), enlace local / metadatos de nube (169.254.x), CGNAT (100.64/10), IPv6 ULA (fc00::/7) y enlace local (fe80::/10), IPv4 mapeado, y rangos multicast/reservados.

2. Validación DNS en el momento de la conexión — un despachador undici compartido cuyo connect.lookup valida la dirección resuelta (la exacta a la que se conecta el socket). Esto cierra la brecha de re-vinculación DNS / TOCTOU donde un nombre de host público se resuelve a una dirección privada, y se vuelve a ejecutar en cada salto de redirección, por lo que una cadena de redirecciones no puede rebotar hacia tu red interna.

Firecrawl (nivel 1) y Crawl4AI (nivel 2) resuelven y obtienen la URL objetivo por sí mismos, por lo que el despachador de tiempo de conexión anterior no puede cubrirlos. fetchPage y crawlSite llaman a assertResolvedPublic(url) — una resolución de nombre de host única que rechaza cualquier resultado privado/reservado — inmediatamente antes de enviar a cualquiera de los servicios, cerrando el caso común de re-vinculación DNS en esa ruta (ventana TOCTOU más estrecha que la protección de tiempo de conexión, ya que el servicio vuelve a resolver).

Los servicios internos configurados (Firecrawl, Crawl4AI, SearXNG, Ollama, Reranker) se alcanzan mediante sus propias URLs y no están protegidos intencionalmente.

Protección de redirecciones

Las solicitudes de HTTP sin procesar y de la ruta rápida de GitHub usan además redirect: "manual" y rechazan las respuestas 3xx directamente (el encabezado Location nunca se devuelve al llamador). Las sondas que siguen redirecciones (robots.txt, llms.txt, sitemap) están cubiertas por la validación DNS de tiempo de conexión anterior, que vuelve a verificar cada salto.

Exposición del transporte

stdio no tiene superficie de red. El transporte HTTP se vincula a 127.0.0.1 por defecto y no está autenticado en esa configuración; moverlo fuera del loopback sin establecer SEARXNG_MCP_AUTH_TOKEN expone todas las herramientas — incluyendo fetch_url de URL arbitraria y clear_cache destructivo — a cualquier cosa que pueda enrutar al puerto. Ver autenticación del transporte HTTP.

Auditoría de dependencias

CI ejecuta pnpm audit en cada push. El archivo de bloqueo (pnpm-lock.yaml) se confirma para compilaciones reproducibles y auditables.

Manejo de credenciales

El servidor no almacena ni registra credenciales. Las claves API (FIRECRAWL_API_KEY, GITHUB_TOKEN, CRAWL4AI_API_TOKEN) se leen de variables de entorno y se usan solo en solicitudes salientes a sus respectivos servicios.

Validación de entrada

Las variables de entorno se validan al inicio — RERANK_RECENCY_WEIGHT advierte sobre valores NaN, negativos o >1.0. Los parámetros numéricos de herramientas usan z.coerce.number() con restricciones de rango.

Contribuciones

Consulta CONTRIBUTING.md para instrucciones de configuración, convenciones de commits y el proceso de PR.

Pruebas de integración

Una suite de integración real de Valkey que cubre la concurrencia de dominio-BD está controlada por VALKEY_TEST_URL y se omite por completo cuando no está configurada, por lo que un pnpm test simple sigue funcionando sin Valkey presente:

VALKEY_TEST_URL=redis://:<password>@<host>:<port>/<scratch-db> pnpm test

Usa un índice de base de datos temporal — la suite escribe y elimina claves domain:* y se niega a ejecutarse contra el índice 0 o 1 como protección de seguridad.

Licencia

MIT