Searxng Mcp

CLI or API | MCP | Agent

Version: 2.1.0

Документация — Инструкции по установке, развертыванию, использованию в MCP-инструменте, Python API и консольных скриптах, а также рекомендации по подготовке экземпляра SearXNG поддерживаются в официальной документации.

Related MCP server: SearXNG MCP Server

Обзор

Searxng Mcp — это сервер Agent и Model Context Protocol (MCP) производственного уровня, предназначенный для прямого взаимодействия с SearXNG Search Engine MCP Server для Agentic AI!.

Ключевые возможности

• Консолидированные MCP-инструменты с маршрутизацией действий: минимизируют накладные расходы на токены и устраняют раздувание инструментов в контекстах LLM, группируя методы в оптимизированные переключаемые модули инструментов.

• Безопасность корпоративного уровня: всесторонняя поддержка политик Eunomia, делегирования OIDC-токенов и детального отслеживания контекста выполнения.

• Встроенный графовый агент: встроенный агент Pydantic AI, поддерживающий Agent Control Protocol (ACP) и стандартные веб-интерфейсы (AG-UI).

• Встроенная телеметрия и трассировка: готовый экспорт OpenTelemetry и нативная трассировка Langfuse.

CLI или API

Этот агент оборачивает API SearXNG Search Engine MCP Server для Agentic AI!. Вы можете взаимодействовать с ним программно или через встроенные точки входа выполнения.

Подробные инструкции по использованию базовых оберток API, расширенных привязок схем и справочников SDK для разработчиков поддерживаются в docs/index.md.

MCP

Этот сервер использует динамические инструменты с маршрутизацией действий для оптимизации накладных расходов на токены и максимальной совместимости с IDE.

Доступные MCP-инструменты

Таблица ниже автоматически генерируется из MCP-сервера — не редактируйте её вручную.

Сокращенные инструменты с маршрутизацией действий (MCP_TOOL_MODE=condensed)

4 инструмента с маршрутизацией действий · 0 подробных инструментов 1:1. Каждый включен, если только его переключатель <DOMAIN>TOOL не установлен в false; MCP_TOOL_MODE выбирает поверхность (по умолчанию intent — шесть глагольных инструментов, детальный набор загружается по требованию · condensed с маршрутизацией действий · verbose 1:1 · both). Автосгенерировано — не редактировать.

Подробные схемы инструментов, формы параметров и ограничения валидации сохранены в docs/usage.md.

Динамический выбор и видимость инструментов

Этот MCP-сервер поддерживает динамический выбор набора инструментов и фильтрацию видимости во время выполнения. Это позволяет ограничить набор доступных инструментов, чтобы не раздувать контекстное окно LLM.

Вы можете настроить фильтрацию инструментов через несколько каналов ввода:

• Аргументы CLI: передайте --tools или --toolsets (или их отключенные аналоги --disabled-tools и --disabled-toolsets) при запуске.

• Переменные окружения: задайте стандартные переменные окружения:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Заголовки HTTP SSE-запросов: передавайте пользовательские заголовки при инициализации транспорта:

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

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

• Параметры запроса HTTP SSE: добавляйте параметры запроса непосредственно к URL вашего транспортного соединения:

  • ?tools=tool1,tool2

  • ?tags=tag1

Когда указаны строки запроса или параметры, не использующий LLM уровень разрешения графа знаний (с помощью DynamicToolOrchestrator) сопоставляет намерения запроса с известными тегами, именами или описаниями инструментов, с безопасным резервным вариантом и автоматическим фоновым обновлением кэша каждые 24 часа.

Примеры конфигурации MCP

Установите дополнительный пакет [mcp], ориентированный на коннекторы. В примерах используется searxng-mcp[mcp] для добавления FastMCP / FastAPI через agent-utilities[mcp]; необходимое ядро Agent Utilities по-прежнему включает epistemic-graph[full]. Дополнительный пакет [agent-runtime] дополнительно включает оркестрацию моделей.

Транспорт stdio (локальные IDE — 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"
      }
    }
  }
}

Ссылки на среду выполнения требуют лаунчера с поддержкой алиасов, такого как GraphOS. Другие лаунчеры должны опускать эти записи и внедрять разрешенные значения через собственную границу секретов среды выполнения.

Транспорт Streamable-HTTP (сетевой / продакшен)

{
  "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"
      }
    }
  }
}

В качестве альтернативы подключитесь к предварительно развернутому экземпляру Streamable-HTTP по url:

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

Запустите проверенный образ контейнера как дочерний процесс stdio с минимальными привилегиями (без слушателя или опубликованного порта):

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

Для контейнерного сетевого HTTP укажите аутентифицированный TLS-вход (или прямой серверный TLS), точный MCP_ALLOWED_HOSTS и точную политику CIDR доверенного прокси через профиль развертывания, принадлежащий оператору. Генератор не создает неаутентифицированный слушатель вне loopback.

Автосгенерировано из env-поверхности, считанной из кода (MCP_TOOL_MODE + переменные пакета) — не редактировать.

Дополнительные параметры развертывания

searxng-mcp может работать как локальный процесс stdio или контейнер, либо за удаленной сетевой границей. Руководство по развертыванию содержит подробный транспортный контракт.

• Локальный контейнер — запустите проверенный неизменяемый образ как дочерний процесс stdio с минимальными привилегиями, без слушателя или опубликованного порта.

• Удаленный URL — подключитесь через предоставленный оператором аутентифицированный HTTPS-вход. Храните его URL, исходящие ссылки на идентификаторы, профиль доверия и точный MCP_ALLOWED_HOSTS в AgentConfig.

Агент

Этот репозиторий содержит полностью интегрированного графового агента Pydantic AI. Он общается через Agent Control Protocol (ACP) и бесшовно взаимодействует с Agent Web UI (AG-UI) и терминальным интерфейсом.

Запуск CLI агента

Чтобы запустить интерактивного агента командной строки:

# Set credentials
export SEARXNG_URL="your_value"

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

Оркестрация Docker Compose

Следующий docker/agent.compose.yml настраивает агента, веб-интерфейс и терминальный интерфейс вместе:

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"

Подробные объяснения архитектуры графовых узлов, настройки пользовательских навыков и руководства по агентной трассировке доступны в docs/deployment.md.

Безопасность и управление

Построенный непосредственно на готовом к корпоративному использованию ядре agent-utilities, полностью поддерживает стандартные параметры безопасности:

Контроль доступа и применение политик

• Политики Eunomia: детальная авторизация инструментов на основе политик. Поддерживает режимы none, локальный embedded (mcp_policies.json) или централизованный remote.

• Делегирование OIDC-токенов: соответствует обмену токенами RFC 8693 для передачи аутентифицирующих учетных данных пользователя от Web UI / ACP → Agent → MCP.

• Ограниченные учетные данные: контекст выполнения ограничен конкретной идентичностью вызывающего.

Сетка безопасности времени выполнения

Переменные окружения

Переменные окружения пакета

Унаследованные переменные agent-utilities (применяются к каждому коннектору)

20 переменных пакета + 16 унаследованных. Автоматически сгенерировано из .env.example + общего набора agent-utilities — не редактировать.

Каждая переменная, которую читает сервер. См. .env.example как отправную точку для копирования.

Подключение SearXNG

{"type": "text"}

MCP-сервер / транспорт

Телеметрия и управление

Установка

Выберите дополнительный пакет, соответствующий тому, что вы хотите запустить:

# 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]"

Образы контейнеров (:mcp и :agent)

Один многоступенчатый docker/Dockerfile собирает два образа подходящего размера, выбираемых с помощью --target:

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 запускает ориентированный на коннектор сервер :mcp; docker/agent.compose.yml запускает агента (неизменяемый дайджест агента) с совместно размещённым сайдкаром :mcp.

База данных графа знаний (epistemic-graph)

Как [mcp], так и [agent] включают движок epistemic-graph через обязательную базовую зависимость Agent Utilities (epistemic-graph[full]). Дополнительный пакет [mcp] сохраняет сервер ориентированным на коннектор; [agent] дополнительно включает оркестрацию моделей. Локальные развёртывания могут использовать встроенный движок. Для продакшена или общего состояния запускайте epistemic-graph как выделенную службу базы данных и настройте среду выполнения для её использования. Рецепты развёртывания (одноузловой + Raft HA), конфигурация подключения и диаграммы архитектуры описаны в руководстве по развёртыванию epistemic-graph.

Документация

Полная документация опубликована на официальном сайте документации и является рекомендуемым справочником по установке, развёртыванию и повседневной эксплуатации.

AGENTS.md — каноническое руководство для участников и агентов.

Владельцы репозитория

Вклад

Вклад приветствуется! Пожалуйста, обеспечьте качество кода, выполнив локальные проверки перед отправкой запросов на включение:

• Форматируйте код с помощью ruff format .

• Проверяйте код с помощью ruff check .

• Проверяйте безопасность типов с помощью mypy .

• Выполняйте тестовые наборы с помощью pytest

Развёртывание с помощью agent-utilities-deployment

Разверните этот пакет с помощью консолидированного рабочего процесса agent-utilities-deployment. Он выбирает путь установленного пакета, редактируемого исходного кода или неизменяемого контейнера; записывает только ссылки на секреты времени выполнения и TLS-профили в AgentConfig; и выполняет проверки doctor, регистрации, политик, наблюдаемости и отката. Попросите вашего агента "развернуть searxng-mcp с помощью agent-utilities-deployment".

Репозиторий не содержит профиля развёртывания, значений учётных данных, путей к сертификатам или конечных точек, зависящих от окружения. Предоставьте их во время выполнения через AgentConfig и настроенного поставщика секретов.

Контракт управляемых возможностей

Этот пакет поставляется с компактной канонической поверхностью навыков, а специализированные процедуры хранятся в виде связанных рабочих процессов. Текущие инструменты MCP, метаданные навыков, connector_manifest.yml, онтология, сопоставления, формы, фикстуры, миграции, отпечатки схем инструментов и сертификационные метаданные образуют единый версионируемый контракт возможностей. Проверяйте их вместе; не полагайтесь на устаревшие имена инструментов или исторические обёртки навыков для конкретных задач.

Runtime-эндпоинты, учетные данные, доверие к сертификатам, идентичность тенанта, хранение и политика наблюдаемости являются входными параметрами развертывания и никогда не являются упакованными значениями. См. Конфигурация, доверие и конфиденциальность перед включением сетевого транспорта, приема коннекторов, делегирования GraphOS или экспорта трассировок.