SearXNG MCP-сервер

Сервер протокола контекста модели (MCP), который предоставляет возможности веб-поиска путем интеграции с экземпляром SearXNG.

Возможности

• Веб-поиск: Выполнение мощного агрегированного поиска по нескольким поисковым системам.

• Обнаружение: Программное получение доступных категорий и поисковых систем.

• Stateless HTTP: Совместимость с любым стандартным клиентом JSON-RPC.

• Гибкая конфигурация: Поддержка переменных окружения и аргументов командной строки.

Пример compose.yml для запуска SearXNG с MCP-сервером

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - 8080:8080
    volumes:
      - ./searxng/etc/:/etc/searxng/
      - ./searxng/data/:/var/cache/searxng/
    restart: always

  searxng-mcp:
    image: ghcr.io/aicrafted/searxng-mcp:latest
    restart: unless-stopped
    depends_on:
      # Ensure SearXNG starts before the MCP server
      - searxng
    environment:
      SEARXNG_URL: http://searxng:8080
      MCP_HOST: 0.0.0.0
      MCP_PORT: 32123
      MCP_TRANSPORT: "http"
    ports:
      - "32123:32123"

Конфигурация MCP-клиента

HTTP-транспорт (рекомендуется)

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:32123/mcp"
    }
  }
}

SSE-транспорт

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://localhost:32123/sse"
    }
  }
}

Примечание: SSE-транспорт использует эндпоинт /sse, а не /mcp. HTTP-транспорт использует /mcp.

Предварительные требования для запуска из исходного кода

• Python 3.10+

• Запущенный экземпляр SearXNG.

Установка

1. Клонируйте репозиторий и перейдите в директорию.

2. Установите зависимости:

   pip install -r requirements.txt

3. Настройте файл .env (опционально):

   SEARXNG_URL=http://your-searxng-instance:8080
   MCP_PORT=32123
   MCP_HOST=127.0.0.1

Использование

Запустите сервер с помощью uv или стандартного python:

python searxng_mcp.py --transport http --port 32123 --searxng http://searx.lan

Запуск с помощью Docker

1. Сборка образа:

   docker build -t searxng-mcp .

2. Запуск контейнера:

   docker run -d \
     -p 32123:32123 \
     -e SEARXNG_URL=http://your-searxng-instance:8080 \
     --name searxng-mcp \
     searxng-mcp

Варианты транспорта

• stdio: Стандартный ввод/вывод (по умолчанию для некоторых MCP-клиентов).

• http: Stateless HTTP (streamable-http).

• sse: Server-Sent Events.

Руководство по возможностям поиска

SearXNG агрегирует результаты из различных источников. В этом руководстве описаны возможности, доступные через инструмент web_search.

Категории поиска

Категории помогают уточнить поиск по типу контента. Используйте их в параметре categories (через запятую).

Поддерживаемые поисковые системы

SearXNG может выполнять запросы к более чем 130 системам. Настроенные системы обычно включают:

• Веб: Google, Brave, DuckDuckGo, Qwant, Startpage

• Знания: Wikipedia, Wikidata

• Разработка: GitHub, StackOverflow, PyPI

• Социальные сети: Reddit, Twitter/X

Расширенные параметры поиска

• categories: Фильтрация по конкретным типам (например, news,it).

• engines: Принудительное использование конкретных систем (например, google,wikipedia).

• language: Указание языка поиска (например, en, es, fr).

• pageno: Навигация по нескольким страницам результатов.

• time_range: Фильтрация по дате (day, month, year).

• safesearch: Управление фильтрацией контента (0=Нет, 1=Умеренно, 2=Строго).

Программное обнаружение

Используйте инструмент web_search_info для динамического получения списка включенных категорий и поисковых систем вашего экземпляра.

Устранение неполадок в Windows

localhost недоступен во время работы Docker-контейнера

Симптом: http://localhost:<port>/ возвращает ошибку соединения или обращается не к той службе, но curl изнутри контейнера работает нормально.

Первопричина: «Призрак» перенаправления портов WSL2

WSL2 автоматически перенаправляет порты из Linux VM на хост Windows с помощью wslrelay.exe. Когда процесс внутри WSL слушает порт, WSL создает ретранслятор, привязанный к [::1]:<port> (IPv6 loopback) на стороне Windows.

Когда этот процесс WSL останавливается, wslrelay.exe часто не освобождает порт. Запись ретранслятора остается активной как «зомби-слушатель» на [::1]:<port>.

Позже, когда Docker отображает контейнер на тот же порт хоста, он корректно привязывается к 0.0.0.0:<port> — но [::1]:<port> уже занят устаревшим ретранслятором.

В Windows localhost сначала разрешается в ::1 (IPv6). Поэтому запросы браузера и curl к localhost:<port> попадают на «мертвую» запись wslrelay.exe, а не в Docker-контейнер, что приводит к ошибке соединения или неожиданному ответу.

Подключение через явный IPv4-адрес 127.0.0.1:<port> обходит ретранслятор и корректно достигает Docker.

Как диагностировать:

# Check what is listening on the port
netstat -ano | findstr :<port>

# Identify the processes
Get-Process -Id <pid1>,<pid2> | Select-Object Id,Name

Если вы видите две записи для одного и того же порта — одну, принадлежащую com.docker.backend, и другую от wslrelay — это и есть проблема.

Обходные пути:

Постоянное исправление:

После wsl --shutdown перезапустите Docker-контейнер. Ретранслятор больше не будет существовать, и localhost:<port> будет работать нормально, пока тот же порт снова не будет использован внутри WSL.

Предотвращение:

Если вы регулярно запускаете службы на одном и том же порту как в WSL, так и в Docker, выберите один из вариантов:

• Всегда используйте Docker для этой службы, никогда не используйте WSL напрямую

• Используйте разные порты для разработки в WSL и для продакшн-экземпляров в Docker

• Добавьте явную привязку 127.0.0.1:<port>:<port> в docker-compose.yml для принудительного использования IPv4

См. также

• Документация по сети WSL2

• Трекер проблем WSL на GitHub: поиск по wslrelay port leak