🔍 SearXNG MCP-сервер

Приватный веб-поиск для ИИ-ассистентов — подключите любой экземпляр SearXNG к Claude, Cursor и другим.

MCP-сервер, интегрирующий API SearXNG, предоставляющий ИИ-ассистентам возможности веб-поиска.

✨ Рекомендован в GitHub MCP Registry.

Быстрый старт

Добавьте в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Замените YOUR_SEARXNG_INSTANCE_URL на URL вашего экземпляра SearXNG (например, https://searxng.example.com).

Возможности

• Веб-поиск: Общие запросы, новости, статьи с поддержкой постраничной навигации.
• Структурированный вывод: Выберите форматированный текст или исходный JSON в формате SearXNG через response_format.
• Прямые ответы и метаданные: Текстовые результаты отображают ответы, исправления, предложения и инфобоксы SearXNG перед списком результатов.
• Поисковые подсказки: Автодополнение запросов через эндпоинт /autocompleter.
• Обнаружение возможностей экземпляра: Просмотр настроенных категорий, движков, настроек по умолчанию, локалей и плагинов из /config.
• Чтение URL: Расширенное извлечение контента с поддержкой пагинации, фильтрации по разделам и извлечения заголовков.
• Интеллектуальное кэширование: Кэширование контента URL с TTL (временем жизни) для повышения производительности и сокращения избыточных запросов.
• Постраничная навигация: Управление страницей результатов.
• Фильтрация по времени: Фильтрация результатов по временному диапазону (день, неделя, месяц, год).
• Выбор языка: Фильтрация результатов по предпочтительному языку.
• Безопасный поиск: Управление уровнем фильтрации контента для результатов.
• Фильтрация по релевантности: Отсеивание низкорелевантных результатов поиска с помощью min_score.

Почему mcp-searxng?

Как это работает

mcp-searxng — это автономный MCP-сервер — отдельный процесс Node.js, к которому ваш ИИ-ассистент подключается для веб-поиска. Он обращается к любому экземпляру SearXNG через его HTTP JSON API.

Не плагин SearXNG: Этот проект не может быть установлен как нативный плагин SearXNG. Укажите его URL для любого существующего экземпляра SearXNG, установив переменную SEARXNG_URL.

ИИ-ассистент (например, Claude)
        │  Протокол MCP
        ▼
  mcp-searxng  (этот проект — процесс Node.js)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  Экземпляр SearXNG

Инструменты

• searxng_web_search
• Выполнение веб-поиска с поддержкой постраничной навигации

• Входные параметры:

  • query (строка): Поисковый запрос. Эта строка передается во внешние поисковые сервисы.
  • pageno (число, опционально): Номер страницы результатов, начинается с 1 (по умолчанию 1)
  • time_range (строка, опционально): Фильтр результатов по временному диапазону — одно из: "day", "week", "month", "year" (по умолчанию: нет)
  • language (строка, опционально): Код языка для результатов (например, "en", "fr", "de") или "all" (по умолчанию: "all")
  • safesearch (число, опционально): Уровень фильтрации безопасного поиска (0: Нет, 1: Умеренный, 2: Строгий) (по умолчанию: настройка экземпляра)
  • min_score (число, опционально): Минимальный показатель релевантности от 0.0 до 1.0. Результаты с меньшим показателем отсеиваются.
  • num_results (число, опционально): Максимальное количество возвращаемых результатов, от 1 до 20. Применяется лимит SEARXNG_MAX_RESULTS.
  • categories (строка, опционально): Категории SearXNG через запятую (например, "news", "it,science"). Когда доступен конфиг /config, значения очищаются и нормализуются без учета регистра в соответствии с каноническими именами категорий экземпляра; неизвестные значения отвергаются с перечнем доступных категорий. Если /config недоступен, значения передаются как есть с предупреждением. По умолчанию: настройка экземпляра SearXNG.
  • engines (строка, опционально): Имена движков SearXNG через запятую (например, "google,bing,ddg", "semantic scholar"). Когда доступен конфиг /config, значения очищаются и нормализуются без учета регистра в соответствии с каноническими именами движков, включая движки, отключенные по умолчанию; неизвестные значения отвергаются с перечнем доступных движков. Если /config недоступен, значения передаются как есть с предупреждением. По умолчанию: настройка экземпляра SearXNG.
  • response_format (строка, опционально): Формат ответа, либо "text" для форматированного вывода для чтения агентом, либо "json" для исходного JSON SearXNG с фильтрованным/срезанным results. (по умолчанию: "text")

• searxng_search_suggestions

• Получение подсказок автодополнения для уточнения поисковых запросов

• Входные параметры:

  • query (строка): Частичный или полный запрос для автодополнения.
  • language (строка, опционально): Код языка для подсказок (например, "en", "fr", "de") или "all" (по умолчанию: "all")

• searxng_instance_info

• Обнаружение категорий, движков, настроек по умолчанию, локалей и плагинов, доступных в настроенном экземпляре SearXNG

• Входные параметры:

  • includeEngines (булево, опционально): Включать имена включенных движков в ответ. (по умолчанию: false)
  • includeDisabled (булево, опционально): Включать имена отключенных движков, если includeEngines равен true. (по умолчанию: false)
  • category (строка, опционально): Фильтровать категории и движки по одному имени категории.
  • refresh (булево, опционально): Игнорировать кэш процесса и получать свежие данные /config. (по умолчанию: false)

• web_url_read

• Чтение и конвертация контента URL в markdown с расширенными параметрами извлечения контента
• Входные параметры:
  • url (строка): URL для получения и обработки
  • startChar (число, опционально): Начальная позиция символа для извлечения контента (по умолчанию: 0)
  • maxLength (число, опционально): Максимальное количество возвращаемых символов
  • section (строка, опционально): Извлекать контент под определенным заголовком (ищет текст заголовка)
  • paragraphRange (строка, опционально): Возвращать определенные диапазоны абзацев (например, '1-5', '3', '10-')
  • readHeadings (булево, опционально): Возвращать только список заголовков вместо полного контента

Установка

NPM (глобальная установка)

npm install -g mcp-searxng

{
"mcpServers": {
  "searxng": {
    "command": "mcp-searxng",
    "env": {
      "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
    }
  }
}
}

Docker

Готовый образ:

docker pull isokoliuk/mcp-searxng:latest

Подписи образов можно проверить с помощью Cosign — см. инструкции в SECURITY.md).

{
"mcpServers": {
  "searxng": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-e", "SEARXNG_URL",
      "isokoliuk/mcp-searxng:latest"
    ],
    "env": {
      "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
    }
  }
}
}

Для передачи дополнительных переменных окружения добавьте -e VAR_NAME в args и переменную в env.

Локальная сборка:

docker build -t mcp-searxng:latest -f Dockerfile .

Используйте ту же конфигурацию, заменив isokoliuk/mcp-searxng:latest на mcp-searxng:latest.

Docker Compose

docker-compose.yml:

services:
mcp-searxng:
  image: isokoliuk/mcp-searxng:latest
  stdin_open: true
  environment:
    - SEARXNG_URL=YOUR_SEARXNG_INSTANCE_URL
    # Добавьте дополнительные переменные по необходимости — см. CONFIGURATION.md

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

{
"mcpServers": {
  "searxng": {
    "command": "docker-compose",
    "args": ["run", "--rm", "mcp-searxng"]
  }
}
}

HTTP-транспорт

По умолчанию сервер использует STDIO. Установите MCP_HTTP_PORT для включения HTTP-режима:

{
"mcpServers": {
  "searxng-http": {
    "command": "mcp-searxng",
    "env": {
      "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL",
      "MCP_HTTP_PORT": "3000"
    }
  }
}
}

Эндпоинты: POST/GET/DELETE /mcp (протокол MCP), GET /health (проверка работоспособности)

Тестирование:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng
curl http://localhost:3000/health

Конфигурация

Установите SEARXNG_URL на URL вашего экземпляра SearXNG. Все остальные переменные опциональны.

Полный справочник переменных окружения: CONFIGURATION.md)

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

403 Forbidden от SearXNG

Вероятно, в вашем экземпляре SearXNG отключен формат JSON. Отредактируйте settings.yml (обычно /etc/searxng/settings.yml):

search:
  formats:
    - html
    - json

Перезапустите SearXNG (docker restart searxng), затем проверьте:

curl 'http://localhost:8080/search?q=test&format=json'

Вы должны получить ответ в формате JSON. Если нет, убедитесь, что файл правильно смонтирован, а отступы в YAML верны.

См. также: Документация настроек SearXNG · обсуждение

Не удается включить JSON? (запасной вариант HTML)

Если вы вынуждены использовать публичный экземпляр, который вы не контролируете, и он отклоняет format=json (упомянутая ошибка 403), вместо редактирования сервера установите флаг для подключения:

"SEARXNG_HTML_FALLBACK": "true"

Поиск, получающий 403/404 или ответ не в формате JSON, автоматически повторяется без format=json и парсится из обычной HTML-страницы результатов.

• При успехе: вы получаете нормальные результаты (название, URL, фрагмент). В JSON-режиме они помечаются как sourceFormat: "html", а в текстовом режиме добавляется строка "Примечание: Результаты распознаны из HTML-резервного варианта SearXNG; метаданные ограничены." Показатели релевантности и имена движков из HTML недоступны.
• При неудаче: парсинг выполняется по мере возможностей и зависит от темы/версии экземпляра, поэтому некоторые результаты могут быть пропущены или малочисленны. Если сама HTML-страница также не загружается — по-прежнему заблокирована, лимит превышен (429), требует аутентификации (401) или ошибка сервера (5xx) — исходная ошибка выводится без изменений. Резервный вариант срабатывает только при 403/404/ответе не в JSON, никогда при ошибках аутентификации или сети.

Включение JSON на управляемом вами экземпляре (см. выше) остается рекомендуемой конфигурацией — резервный вариант служит средством совместимости, а не заменой.

Участие в разработке

См. CONTRIBUTING.md)

История звезд

Лицензия

MIT — подробности см. в LICENSE).