🔍 SearXNG MCP Server

Конфиденциальный веб-поиск для AI-помощников — используйте экземпляр SearXNG, управляемый оператором, или доверенную установку SearXNG с Claude, Cursor и другими.

Сервер MCP, интегрирующий API SearXNG, обеспечивает AI-помощникам веб-поиск.

✨ Включено в реестр MCP на GitHub.

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

Вам нужен существующий экземпляр SearXNG с включенным JSON-поискованием. Этот проект соединяет MCP-клиент с SearXNG; он не устанавливает SearXNG. Используйте экземпляр, которым вы управляете или которому доверяете. При необходимости начните с руководств по самостоятельному размещению или публичному экземпляру.

Выберите способ подключения:

Ваше окружение	Начать здесь
Клиент запускает сервер локально	Установите Node.js 22 или выше, затем используйте приведённый ниже пример NPX или свой рецепт клиента.
Клиент запускает контейнер Docker	Используйте рецепт Docker/STDIO в разделе Установка.
У вас Independently running HTTP service	Используйте HTTP-рецепт вашего клиента с полным URL /mcp.
Нужно запустить HTTP-сервис	Следуйте руководству по HTTP-серверу.

Для клиентов, использующих JSON (например Claude Desktop), добавьте:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": { "SEARXNG_URL": "https://search.example.com" }
    }
  }
}

Замените примерный URL на ваш базовый URL SearXNG. Другие клиенты используют другие конфигурационные формы: выберите свой рецепт клиента.

Оставляйте MCP_HTTP_PORT пустым для локального STDIO. Docker также требует прокидывания окружения в контейнер.

Перезагрузите клиента, проверьте его инвентарь инструментов MCP, затем попросите его выполнить поиск по документации SearXNG. Простой вызов инструмента —

searxng_web_search с {"query":"SearXNG"}. Только обнаружение не тестирует подключение к SearXNG. Если вызов не удаётся, начните с устранения неполадок.

Особенности

Поиск с пагинацией, фильтрами, прямыми ответами и полным или компактным выводом текста/JSON.
Чтение HTML, структурированного текста и ограниченного текста PDF; просмотр заголовков или выбранных разделов.
Обнаружение возможностей инстанса и получение подсказок к запросам.
Необязательное реплика--фейловер/разветвление, HTML-фолбэк, кеширование, прокси и браузерные решатели.
Локальная STDIO или потоковый HTTP, с статическим Bearer-токеном и при необходимости защитой OAuth.

См. руководство по инструментам для возможностей и ограничений, справочник по настройкам — для параметров, и исторические данные развёртывания — для обоснований планирования ресурсов с учётом ограничений.

Зачем mcp-searxng?

Сравнение возможностей на 2026-07-29

По состоянию на 2026-07-29 результат сравнения ниже охватывает официальные проекты Brave MCP, Exa MCP и Firecrawl MCP.

«Пагинация» означает доступ к странице или контролю смещения. «Self-hosted» означает, что сервис поиска может работать под вашим контролем. «Free / No API key» означает, что сервер MCP не требует платного API-ключа у поставщика поиска; вы всё равно управляете или выбираете базовую инстанцию SearXNG.

	Brave MCP	Exa MCP	Firecrawl MCP	mcp-searxng
Web Search	✓	✓	✓	✓
Read URL	✗	✓	✓	✓
Pagination	✓	✗	✓	✓
Self-hosted	✗	✗	Partial	✓
Free / No API key	✗	✗	✗	✓

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

Как работает

MCP client → mcp-searxng → SearXNG → search engines

Клиент либо запускает собственный процесс STDIO, либо подключается к HTTP-сервису.

SEARXNG_URL идентифицирует сервис SearXNG, а не конечную точку MCP. Чтение URL читает выбранный сайт напрямую. Поддерживается список реплик, разделённых точкой с запятой, для взаимозаменяемых развёртываний SearXNG; см. core replica configuration.

STDIO по умолчанию. Наследственные сессии Streamable HTTP по умолчанию являются stateful; клиенты должны отправлять DELETE /mcp по завершении, затем повторно инициализировать, если позже запрос получит HTTP 404 для завершённой сессии. Современные HTTP-запросы и наследуемый режим MCP_HTTP_STATELESS=true являются безсессионными; см. HTTP-transport configuration.

Инструменты

Инструмент	Что делать с ним
searxng_web_search	Находит источники и уточняет результаты
searxng_search_suggestions	Дополняет или уточняет запрос
searxng_instance_info	Проверяет категории, движки и значения по умолчанию
web_url_read	Читает известный URL как текст/Markdown

См. руководство по инструментам для примеров и полного справочника параметров. Необязательный научно-исследовательский рабочий процесс объясняет, как исследовать источники и приводить доказательства.

Установка

Для NPX и npm установка требуется Node.js 22 или новее. Docker-образ включает время выполнения Node.js.

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.

Для интеграции с браузерным решателем укажите FLARESOLVERR_URL, BYPARR_URL, или оба варианта и сделайте доступными из этого контейнера. Режим Dual имеет фиксированный порядок FlareSolverr-first и отсутствует автоматический обратный Failover. Безопасно отрендеренный HTML и явный Byparr PDF-контент читаются напрямую; неоднозначный контент использует guarded replay, с ограниченным повторным воспроизведением для подходящих случаев. Смотрите URL Reader Controls для полного поведения и примера Docker Compose.

Собрать локально:

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=${SEARXNG_URL:?Set SEARXNG_URL in the environment}
      # Добавляйте опциональные переменные по мере необходимости — см. CONFIGURATION.md

Отслеживаемый файл Compose намеренно конфигурационен только под STDIO и не публикует сетевые порты; клиенты MCP запускают его с абсолютным путём к файлу Compose и docker compose run --rm -T, а не через docker compose up. Флаг -T предотвращает выделение псевдо-TTY, чтобы MCP JSON-RPC оставался на уровне сырого стандартного ввода/вывода. Секция Compose не запускается, если клиент MCP не предоставляет SEARXNG_URL.

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

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/docker-compose.yml",
        "run", "--rm", "-T", "mcp-searxng"
      },
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

Если ранее вы использовали отслеживаемый файл как HTTP-сервис на порту 8080, поместите настройки HTTP в незатянутый файл docker-compose.override.yml:

services:
  mcp-searxng:
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MCP_HTTP_PORT=8080
      - MCP_HTTP_HOST=0.0.0.0

Здесь 0.0.0.0 — это привязка по адресу на стороне контейнера; порт на хосте остаётся только для локального доступа. Это переадресование временное и без аутентификации, предназначено только для миграции на одном хосте. Прежде чем добавлять соседние контейнеры или открывать сервис за пределами локальной машины, следуйте усовершенствованным рекомендациям по развёртыванию в SECURITY.md.

HTTP-транспорт

Запускайте HTTP отдельно, затем подключайте клиента. См. руководство по HTTP-серверу для локальных проверок, статической Bearer-аутентификации, требований OAuth и проверки развёртывания.

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

Для локальной настройки по умолчанию требуется параметр SEARXNG_URL. Необязательные режимы, такие как усиленный HTTP и OAuth, имеют сопутствующие требования. Используйте справочник по настройкам для переменных окружения, значений по умолчанию, кеширования, тайм-аутов, прокси, TLS и ограничений.

Необязательный MCP OAuth

HTTP-развертывание может использовать OAuth через внешнего провайдера авторизации. См. варианты аутентификации. Статический Bearer-аутентификация и SearXNG Basic Auth защищают разные соединения.

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

Симптом	Следующая проверка
Сервер отсутствует или отвисает	Запуск клиента/процесса
HTTP-аутентификация, ошибка сессии или прокси	HTTP-соединение
Инструменты возникают, но поиск не работает	Подключение к SearXNG
Пустые, слабые или устаревшие результаты	Фильтры, метаданные upstream и кеш
Ошибка URL/PDF или тайм-аут	Чтение URL

403 Forbidden от SearXNG

JSON-вывод может быть отключён, или слой доступа мог заблокировать запрос. Выполните прямые проверки перед сменой настроек: проверка напрямую SearXNG. Рабочая страница в браузере не доказывает работу JSON API.

Не могу включить JSON? (HTML-фолбэк)

SEARXNG_HTML_FALLBACK=true может повторно попытаться выполнить запросы без JSON как HTML, включая 403/404/не JSON. Парсинг производится наилучшим образом и метаданные ограничены; компактный вывод пропускает маркеры фолбэка. Прочитайте руководство по публичным инстансам перед включением на сервисе, который под вашим контролем: публичные инстансы — JSON отклонён и HTML-фолбэк.

Для сообщения об ошибке соберите минимальный воспроизводимый пример и сопутствующие ошибки: сбор полезных сведений.

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

Найдите руководство по задаче. Эти ссылки открывают текущую документацию ветки main. Неопубликованное поведение помечено; см. соответствующий Git tag при работе с более старой версией.

Внесение вклада

Смотрите CONTRIBUTING.md.

Лицензия

MIT — см. LICENSE для подробностей.