SearXNG MCP Server

{"type":"text"}# Searxng Mcp

CLI oder API | MCP | Agent

Version: 2.1.0

Dokumentation — Installation, Bereitstellung, Nutzung über das MCP-Tool, die Python-API und Konsolenskripte sowie Anleitungen zur Bereitstellung der SearXNG-Instanz finden Sie in der offiziellen Dokumentation.

Related MCP server: SearXNG MCP Server

Übersicht

Searxng Mcp ist ein produktionsreifer Agent- und Model-Context-Protocol-Server (MCP), der eine direkte Schnittstelle zum SearXNG-Suchmaschinen-MCP-Server für Agentic AI bietet.

Hauptfunktionen

• Konsolidierte aktionsgesteuerte MCP-Tools: Minimiert den Token-Overhead und beseitigt Tool-Aufblähung in LLM-Kontexten, indem Methoden in optimierte, umschaltbare Tool-Module gruppiert werden.

• Sicherheit auf Enterprise-Niveau: Umfassende Unterstützung für Eunomia-Richtlinien, OIDC-Token-Delegation und granulare Verfolgung des Ausführungskontexts.

• Integrierter Graph-Agent: Integrierter Pydantic-AI-Agent mit Unterstützung für das Agent Control Protocol (ACP) und standardmäßige Webschnittstellen (AG-UI).

• Native Telemetrie & Tracing: OpenTelemetry-Exporte und natives Langfuse-Tracing direkt einsatzbereit.

CLI oder API

Dieser Agent kapselt die API des SearXNG Search Engine MCP Server for Agentic AI!. Sie können programmatisch oder über seine integrierten Ausführungseinstiegspunkte mit ihm interagieren.

Detaillierte Anweisungen zur Verwendung der zugrunde liegenden API-Wrapper, erweiterten Schema-Bindungen und Entwickler-SDK-Referenzen finden Sie in docs/index.md.

MCP

Dieser Server nutzt dynamische aktionsgesteuerte Tools, um den Token-Overhead zu optimieren und die IDE-Kompatibilität zu maximieren.

Verfügbare MCP-Tools

Die folgende Tabelle wird automatisch vom MCP-Server generiert — nicht von Hand bearbeiten.

Kompakte aktionsgesteuerte Tools (MCP_TOOL_MODE=condensed)

4 aktionsgesteuerte Tools · 0 verbose 1:1-Tools. Jedes ist aktiviert, sofern sein <DOMAIN>TOOL-Schalter nicht auf false gesetzt ist; MCP_TOOL_MODE wählt die Oberfläche (**intent Standard* — die sechs Verb-Tools, granulare Menge bei Bedarf geladen · condensed aktionsgesteuert · verbose 1:1 · both). Automatisch generiert — nicht bearbeiten.*

Detaillierte Tool-Schemas, Parameterformen und Validierungsbeschränkungen sind in docs/usage.md dokumentiert.

Dynamische Tool-Auswahl & Sichtbarkeit

Dieser MCP-Server unterstützt die dynamische Auswahl des Toolsets und die Sichtbarkeitsfilterung zur Laufzeit. Dadurch können Sie die Menge der verfügbaren Tools einschränken, um ein Aufblähen des Kontextfensters des LLM zu verhindern.

Sie können die Tool-Filterung über mehrere Eingabekanäle konfigurieren:

• CLI-Argumente: Übergeben Sie --tools oder --toolsets (oder deren deaktivierte Gegenstücke --disabled-tools und --disabled-toolsets) beim Start.

• Umgebungsvariablen: Definieren Sie standardmäßige Umgebungsvariablen:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP-SSE-Anfrageheader: Übergeben Sie benutzerdefinierte Header während der Transportinitialisierung:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP-SSE-Anfrageabfrageparameter: Fügen Sie Ihrer Transportverbindungs-URL direkt Abfrageparameter hinzu:

  • ?tools=tool1,tool2

  • ?tags=tag1

Wenn Abfragezeichenfolgen oder Parameter angegeben werden, gleicht eine LLM-freie Knowledge-Graph-Auflösungsebene (unter Verwendung von DynamicToolOrchestrator) Abfrageabsichten mit bekannten Tool-Tags, -Namen oder -Beschreibungen ab, mit sicherem Fallback und automatischer 24-Stunden-Hintergrund-Cache-Aktualisierung.

MCP-Konfigurationsbeispiele

Installieren Sie das connector-fokussierte [mcp]-Extra. Die Beispiele verwenden searxng-mcp[mcp], um FastMCP / FastAPI über agent-utilities[mcp] hinzuzufügen; der erforderliche Agent-Utilities-Kern enthält weiterhin epistemic-graph[full]. Das [agent-runtime]-Extra aktiviert zusätzlich die Modellorchestrierung.

stdio-Transport (lokale IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

Laufzeitreferenzen erfordern einen alias-bewussten Launcher wie GraphOS. Andere Launcher müssen diese Einträge weglassen und die aufgelösten Werte über ihre eigene Laufzeit-Geheimnisgrenze injizieren.

Streamable-HTTP-Transport (vernetzt / Produktion)

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

Alternativ können Sie eine Verbindung zu einer bereits bereitgestellten Streamable-HTTP-Instanz per url herstellen:

{
  "mcpServers": {
    "searxng-mcp": {
      "url": "http://localhost:8000/searxng-mcp/mcp"
    }
  }
}

Führen Sie ein geprüftes Container-Image als stdio-Kindprozess mit minimalen Rechten aus (kein Listener oder veröffentlichter Port):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e SEARCH_APPTOOL=true \
  -e SEARXNG_EMBEDDED=true \
  -e SEARXNG_KG_INGEST=true \
  -e USE_RANDOM_INSTANCE=false \
  registry.example.invalid/searxng-mcp@sha256:<digest> searxng-mcp

Für containerisiertes Netzwerk-HTTP stellen Sie einen authentifizierten TLS-Ingress (oder direktes Server-TLS), exakte MCP_ALLOWED_HOSTS und eine exakte Trusted-Proxy-CIDR-Richtlinie über das vom Betreiber verwaltete Bereitstellungsprofil bereit. Der Generator erzeugt keinen unauthentifizierten Nicht-Loopback-Listener.

Automatisch aus der codegelesenen Env-Oberfläche generiert (MCP_TOOL_MODE + Paketvariablen) — nicht bearbeiten.

Zusätzliche Bereitstellungsoptionen

searxng-mcp kann als lokaler stdio-Prozess oder Container oder hinter einer entfernten Netzwerkgrenze ausgeführt werden. Der Bereitstellungsleitfaden enthält den detaillierten Transportvertrag.

• Lokaler Container — starten Sie ein geprüftes unveränderliches Image als stdio-Kindprozess mit minimalen Rechten, ohne Listener oder veröffentlichten Port.

• Remote-URL — verbinden Sie sich über einen vom Betreiber bereitgestellten authentifizierten HTTPS-Ingress. Bewahren Sie dessen URL, ausgehende Identitätsreferenzen, Vertrauensprofil und exakte MCP_ALLOWED_HOSTS in AgentConfig auf.

Agent

Dieses Repository enthält einen vollständig integrierten Pydantic-AI-Graph-Agenten. Er kommuniziert über das Agent Control Protocol (ACP) und interagiert nahtlos mit der Agent-Web-UI (AG-UI) und der Terminal-Schnittstelle.

Ausführen der Agent-CLI

Um den interaktiven Kommandozeilen-Agenten zu starten:

# Set credentials
export SEARXNG_URL="your_value"

# Run the agent server
searxng-agent --provider openai --model-id gpt-4o

Docker-Compose-Orchestrierung

Die folgende docker/agent.compose.yml konfiguriert den Agenten, die Web-UI und die Terminal-Schnittstelle gemeinsam:

version: '3.8'

services:
  searxng-mcp-mcp:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-mcp
    hostname: searxng-mcp-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  searxng-mcp-agent:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-agent
    hostname: searxng-mcp-agent
    restart: always
    depends_on:
      - searxng-mcp-mcp
    env_file:
      - ../.env
    command: [ "searxng-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9001
      - MCP_URL=http://searxng-mcp-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9001:9001"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9001/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Detaillierte Erläuterungen zur Graph-Knotenarchitektur, Konfigurationen für benutzerdefinierte Fähigkeiten und Anleitungen für agentische Traces finden Sie in docs/deployment.md.

Sicherheit & Governance

Direkt auf dem unternehmensreifen agent-utilities-Kern aufgebaut, werden die standardmäßigen Sicherheitsparameter vollständig unterstützt:

Zugriffskontrolle & Richtliniendurchsetzung

• Eunomia-Richtlinien: Fein granulare, richtliniengesteuerte Tool-Autorisierung. Unterstützt none, lokale embedded-Modi (mcp_policies.json) oder zentralisierte remote-Modi.

• OIDC-Token-Delegation: Konform mit RFC 8693-Token-Austausch, um authentifizierende Benutzeranmeldeinformationen von Web-UI / ACP → Agent → MCP weiterzuleiten.

• Bereichsbezogene Anmeldeinformationen: Ausführungskontext läuft auf die spezifische Aufruferidentität beschränkt.

Laufzeit-Sicherheitsraster

Umgebungsvariablen

Paket-Umgebungsvariablen

Geerbte Agent-Utilities-Variablen (gelten für jeden Connector)

20 Paket- + 16 geerbte Variable(n). Automatisch generiert aus .env.example + dem gemeinsamen Agent-Utilities-Set — nicht bearbeiten.

Jede Variable, die der Server liest. Siehe .env.example als Copy-Paste-Ausgangspunkt.

SearXNG-Verbindung

MCP-Server / Transport

Telemetrie & Governance

Installation

Wählen Sie das Extra, das zu dem passt, was Sie ausführen möchten:

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "searxng-mcp[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "searxng-mcp[agent]"

# Everything (development)
uv pip install "searxng-mcp[all]"      # or: python -m pip install "searxng-mcp[all]"

Container-Images (:mcp vs. :agent)

Ein mehrstufiges docker/Dockerfile erstellt zwei passend dimensionierte Images, die über --target ausgewählt werden:

docker build --target mcp   -t example/searxng-mcp:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/searxng-mcp:agent-local docker/   # agent runtime

docker/mcp.compose.yml führt den verbindungsorientierten :mcp-Server aus; docker/agent.compose.yml führt den Agenten (immutable agent digest) mit einem am selben Ort abgelegten :mcp-Sidecar aus.

Wissensgraph-Datenbank (epistemic-graph)

Sowohl [mcp] als auch [agent] bringen die epistemic-graph-Engine über die erforderliche Agent-Utilities-Kernabhängigkeit (epistemic-graph[full]) mit. Das Extra [mcp] hält den Server verbindungsorientiert; [agent] aktiviert zusätzlich die Modell-Orchestrierung. Lokale Bereitstellungen können die gebündelte Engine verwenden. Für den Produktionsbetrieb oder gemeinsamen Zustand führen Sie epistemic-graph als dedizierten Datenbankdienst aus und konfigurieren die Laufzeit so, dass sie diesen verwendet. Bereitstellungsrezepte (Einzelknoten + Raft-HA), Verbindungskonfiguration und Architekturdiagramme sind im Bereitstellungshandbuch für epistemic-graph dokumentiert.

Dokumentation

Die vollständige Dokumentation ist als offizielle Dokumentationswebsite veröffentlicht und die empfohlene Referenz für Installation, Bereitstellung und den täglichen Betrieb.

AGENTS.md ist die maßgebliche Anleitung für Mitwirkende/Agenten.

Repository-Inhaber

Mitwirken

Beiträge sind willkommen! Bitte stellen Sie die Codequalität sicher, indem Sie vor dem Einreichen von Pull-Requests lokale Prüfungen ausführen:

• Code mit ruff format . formatieren

• Code mit ruff check . linten

• Typsicherheit mit mypy . validieren

• Test-Suiten mit pytest ausführen

Mit agent-utilities-deployment bereitstellen

Stellen Sie dieses Pakel mit dem konsolidierten agent-utilities-deployment-Workflow bereit. Dieser wählt einen Pfad für installierte Pakete, bearbeitbare Quellen oder unveränderliche Container aus; zeichnet nur Referenzen auf Laufzeitgeheimnisse und TLS-Profile in AgentConfig auf; und führt Arzt-, Registrierungs-, Richtlinien-, Beobachtbarkeits- und Rollback-Gates aus. Bitten Sie Ihren Agenten, "searxng-mcp mit agent-utilities-deployment bereitzustellen".

Das Repository enthält kein Bereitstellungsprofil, keinen Anmeldedatenwert, keinen Zertifikatspfad und keinen umgebungsspezifischen Endpunkt. Stellen Sie diese zur Laufzeit über AgentConfig und den konfigurierten Geheimnisanbieter bereit.

Vertrag für verwaltete Fähigkeiten

Dieses Paket enthält eine kompakte kanonische Fähigkeitsoberfläche mit spezialisierten Verfahren als referenzierte Workflows. Die aktuellen MCP-Tools, Fähigkeitsmetadaten, connector_manifest.yml, Ontologie, Zuordnungen, Formen, Fixtures, Migrationen, Tool-Schema-Fingerabdrücke und Zertifizierungsmetadaten bilden einen versionierten Vertrag für Fähigkeiten. Validieren Sie diese gemeinsam; verlassen Sie sich nicht auf veraltete Tool-Namen oder historische aufgabenspezifische Fähigkeits-Wrapper.

Runtime-Endpunkte, Anmeldedaten, Zertifikatsvertrauen, Mandantenidentität, Aufbewahrung und Observability-Richtlinie sind Eingaben für die Bereitstellung und niemals im Paket enthaltene Werte. Siehe Konfiguration, Vertrauen und Datenschutz, bevor Sie einen Netzwerktransport, eine Connector-Ingestion, eine GraphOS-Delegation oder einen Trace-Export aktivieren.