Расширенный сервер MCP SearXNG

Сервер Model Context Protocol (MCP) для веб-поиска с учетом категорий, веб-скрапинга и инструментов даты/времени. Разработан для бесшовной интеграции с SearXNG и современными клиентами MCP.

Функции

🔍 Поиск в Интернете на базе SearXNG с поддержкой категорий (общие, изображения, видео, файлы, карты, социальные сети)
📄 Извлечение контента веб-сайта с помощью метаданных цитирования и автоматического преобразования URL-адресов Reddit
💾 Кэширование в памяти с автоматической проверкой актуальности
🚦 Ограничение скорости на основе домена для предотвращения злоупотреблений сервисом
🕒 Инструмент даты/времени с учетом часового пояса
⚠️ Надежная обработка ошибок с помощью пользовательских типов исключений
🐳 Dockerized и настраиваемый через переменные среды
⚙️ Сохранение конфигурации между перезапусками контейнера

Related MCP server: OneSearch MCP Server

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

Предпосылки

Docker установлен в вашей системе
Работающий экземпляр SearXNG (размещенный самостоятельно или доступная конечная точка)

Установка и использование

Создайте образ Docker:

docker build -t overtlids/mcp-searxng-enhanced:latest .

Запустите с помощью вашего экземпляра SearXNG (ручной запуск Docker):

docker run -i --rm --network=host \ -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \ -e DESIRED_TIMEZONE="America/New_York" \ overtlids/mcp-searxng-enhanced:latest

В этом примере SEARXNG_ENGINE_API_BASE_URL задан явно. DESIRED_TIMEZONE также явно задан как America/New_York , что соответствует его значению по умолчанию. Если переменная среды не указана с помощью флага -e во время команды docker run , сервер автоматически будет использовать значение по умолчанию, определенное в его Dockerfile (см. таблицу переменных среды ниже). Таким образом, если вы собираетесь использовать значение по умолчанию для DESIRED_TIMEZONE , вы можете опустить флаг -e DESIRED_TIMEZONE="America/New_York" . Однако SEARXNG_ENGINE_API_BASE_URL имеет решающее значение и обычно его необходимо установить в соответствии с адресом вашего конкретного экземпляра SearXNG, если значение по умолчанию Dockerfile ( http://host.docker.internal:8080/search ) не подходит.

Примечание по ручному запуску Docker: эта команда запускает контейнер Docker независимо. Если вы используете клиент MCP (например, Cline в VS Code) для управления этим сервером, клиент запустит собственный экземпляр контейнера, используя настройки, определенные в его собственной конфигурации . Чтобы клиент MCP использовал определенные переменные среды, они должны быть настроены в настройках клиента для этого сервера (см. ниже).

Настройте свой MCP-клиент (например, Cline в VS Code):

Чтобы ваш клиент MCP мог правильно управлять и запускать этот сервер, вы должны определить все необходимые переменные среды в настройках клиента для сервера overtlids/mcp-searxng-enhanced . Клиент MCP будет использовать эти настройки для построения команды docker run .

Ниже приведена рекомендуемая конфигурация по умолчанию для этого сервера в настройках JSON вашего клиента MCP (например, cline_mcp_settings.json ). В этом примере явно перечислены все переменные среды, для которых установлены значения по умолчанию, как определено в Dockerfile . Вы можете скопировать и вставить это напрямую, а затем настроить любые значения по мере необходимости.

{ "mcpServers": { "overtlids/mcp-searxng-enhanced": { "command": "docker", "args": [ "run", "-i", "--rm", "--network=host", "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search", "-e", "DESIRED_TIMEZONE=America/New_York", "-e", "ODS_CONFIG_PATH=/config/ods_config.json", "-e", "RETURNED_SCRAPPED_PAGES_NO=3", "-e", "SCRAPPED_PAGES_NO=5", "-e", "PAGE_CONTENT_WORDS_LIMIT=5000", "-e", "CITATION_LINKS=True", "-e", "MAX_IMAGE_RESULTS=10", "-e", "MAX_VIDEO_RESULTS=10", "-e", "MAX_FILE_RESULTS=5", "-e", "MAX_MAP_RESULTS=5", "-e", "MAX_SOCIAL_RESULTS=5", "-e", "TRAFILATURA_TIMEOUT=15", "-e", "SCRAPING_TIMEOUT=20", "-e", "CACHE_MAXSIZE=100", "-e", "CACHE_TTL_MINUTES=5", "-e", "CACHE_MAX_AGE_MINUTES=30", "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10", "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60", "-e", "IGNORED_WEBSITES=", "overtlids/mcp-searxng-enhanced:latest" ], "timeout": 60 } } }

Ключевые моменты конфигурации клиента MCP:

В приведенном выше примере представлен полный набор аргументов для запуска контейнера Docker со всеми переменными среды, для которых заданы значения по умолчанию.
Чтобы настроить любой параметр, просто измените значение для соответствующей строки -e "VARIABLE_NAME=value" в массиве args в конфигурации вашего клиента MCP. Например, чтобы изменить SEARXNG_ENGINE_API_BASE_URL и DESIRED_TIMEZONE , вам нужно будет изменить соответствующие строки.
Подробное описание каждой переменной и ее значения по умолчанию см. в таблице «Переменные среды» ниже.
Поведение сервера в первую очередь контролируется этими переменными среды. Хотя файл ods_config.json также может влиять на настройки (см. Управление конфигурацией), переменные среды, передаваемые клиентом MCP, имеют приоритет.

Работает в исходном коде (без Docker)

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

1. Установка Python:

Для этого сервера требуется Python 3.9 или более новая версия . Рекомендуется Python 3.11 (используемый в образе Docker).
Вы можете загрузить Python с сайта python.org .

2. Клонируйте репозиторий:

Получите код с GitHub:
git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git cd mcp-searxng-enhanced

3. Создайте и активируйте виртуальную среду (рекомендуется):

Использование виртуальной среды помогает управлять зависимостями и избегать конфликтов с другими проектами Python.
# For Linux/macOS python3 -m venv .venv source .venv/bin/activate # For Windows (Command Prompt) python -m venv .venv .\.venv\Scripts\activate.bat # For Windows (PowerShell) python -m venv .venv .\.venv\Scripts\Activate.ps1

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

Установите необходимые пакеты Python:
pip install -r requirements.txt
Ключевые зависимости включают httpx , BeautifulSoup4 , pydantic , trafilatura , python-dateutil , cachetools и zoneinfo .

5. Убедитесь, что SearXNG доступен:

Вам все еще нужен работающий экземпляр SearXNG. Убедитесь, что у вас есть его базовый URL API (например, http://127.0.0.1:8080/search ).

6. Установите переменные среды:

Сервер настраивается через переменные среды. Как минимум, вам, скорее всего, понадобится установить SEARXNG_ENGINE_API_BASE_URL .
Linux/macOS (bash/zsh):
export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" export DESIRED_TIMEZONE="America/Los_Angeles"
Windows (командная строка):
set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" set DESIRED_TIMEZONE="America/Los_Angeles"
Windows (PowerShell):
$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" $env:DESIRED_TIMEZONE="America/Los_Angeles"
Обратитесь к таблице "Переменные среды" ниже для всех доступных опций. Если не установлено, будут использоваться значения по умолчанию из скрипта или файла ods_config.json (если он есть в корневом каталоге или в ODS_CONFIG_PATH ).

7. Запустите сервер:

Выполните скрипт Python:
python mcp_server.py
Сервер запустится и будет прослушивать клиентские подключения MCP через stdin/stdout.

8. Файл конфигурации (

В качестве альтернативы или в сочетании с переменными окружения вы можете создать файл ods_config.json в корневом каталоге проекта (или по пути, указанному переменной окружения ODS_CONFIG_PATH ). Переменные окружения всегда будут иметь приоритет над значениями в этом файле. Пример: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

Переменные среды

Следующие переменные среды управляют поведением сервера. Вы можете задать их в конфигурации клиента MCP (рекомендуется для серверов, управляемых клиентом) или при запуске Docker вручную.

Переменная	Описание	По умолчанию (из Dockerfile)	Примечания
`SEARXNG_ENGINE_API_BASE_URL`	Конечная точка поиска SearXNG	`http://host.docker.internal:8080/search`	Решающее значение для работы сервера
`DESIRED_TIMEZONE`	Часовой пояс для инструмента даты/времени	`America/New_York`	Например, `America/Los_Angeles` . Список часовых поясов базы данных tz: https://en.wikipedia.org/wiki/List\_of\_tz\_database\_time\_zones
`ODS_CONFIG_PATH`	Путь к постоянному файлу конфигурации	`/config/ods_config.json`	Обычно остается по умолчанию в контейнере.
`RETURNED_SCRAPPED_PAGES_NO`	Максимальное количество страниц, возвращаемых за один поиск	`3`
`SCRAPPED_PAGES_NO`	Максимальное количество страниц для попытки скрейпинга	`5`
`PAGE_CONTENT_WORDS_LIMIT`	Максимальное количество слов на очищенную страницу	`5000`
`CITATION_LINKS`	Включить/отключить события цитирования	`True`	`True` или `False`
`MAX_IMAGE_RESULTS`	Максимальное количество возвращаемых результатов изображения	`10`
`MAX_VIDEO_RESULTS`	Максимальное количество возвращаемых видеорезультатов	`10`
`MAX_FILE_RESULTS`	Максимальное количество возвращаемых результатов файла	`5`
`MAX_MAP_RESULTS`	Максимальное количество возвращаемых результатов карты	`5`
`MAX_SOCIAL_RESULTS`	Максимальное количество результатов в социальных сетях для возврата	`5`
`TRAFILATURA_TIMEOUT`	Время ожидания извлечения контента (секунды)	`15`
`SCRAPING_TIMEOUT`	Время ожидания HTTP-запроса (секунды)	`20`
`CACHE_MAXSIZE`	Максимальное количество кэшированных веб-сайтов	`100`
`CACHE_TTL_MINUTES`	Время жизни кэша (минуты)	`5`
`CACHE_MAX_AGE_MINUTES`	Максимальный срок хранения кэшированного контента (минуты)	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	Максимальное количество запросов на домен в минуту	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	Окно отслеживания ограничения скорости (секунды)	`60`
`IGNORED_WEBSITES`	Список сайтов, которые следует игнорировать, разделенный запятыми	`""` (пустой)	Например, `"example.com,another.org"`

Управление конфигурацией

Сервер использует трехуровневый подход к конфигурации:

Настройки скрипта по умолчанию (жёстко закодированы в Python)
Файл конфигурации (загружается из ODS_CONFIG_PATH , по умолчанию /config/ods_config.json )
Переменные среды (наивысший приоритет)

Файл конфигурации обновляется только когда:

Файл еще не существует (первая инициализация)
Переменные среды явно указаны для текущего запуска

Это гарантирует сохранение пользовательских конфигураций между перезапусками контейнера, если не установлены новые переменные среды.

Инструменты и псевдонимы

Название инструмента	Цель	Псевдонимы
`search_web`	Поиск в Интернете через SearXNG	`search` , `web_search` , `find` , `lookup_web` , `search_online` , `access_internet` , `lookup` *
`get_website`	Соскребать содержимое веб-сайта	`fetch_url` , `scrape_page` , `get` , `load_website` , `lookup` *
`get_current_datetime`	Текущая дата/время	`current_time` , `get_time` , `current_date`

* lookup зависит от контекста:

Если вызван с аргументом url , он сопоставляется с get_website
В противном случае он отображается в search_web

Пример: вызов инструментов

Поиск в Интернете

{ "name": "search_web", "arguments": { "query": "open source ai" } }

или используя псевдоним:

{ "name": "search", "arguments": { "query": "open source ai" } }

Поиск по конкретной категории

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

Скрапинг веб-сайта

{ "name": "get_website", "arguments": { "url": "example.com" } }

или используя псевдоним:

{ "name": "lookup", "arguments": { "url": "example.com" } }

Текущая дата/время

{ "name": "get_current_datetime", "arguments": {} }

или:

{ "name": "current_time", "arguments": {} }

Расширенные функции

Поиск по конкретной категории

Инструмент search_web поддерживает различные категории с настраиваемыми результатами:

изображения : возвращает URL-адреса изображений, заголовки и исходные страницы с возможностью встраивания Markdown.
Видео : возвращает информацию о видео, включая заголовки, источники и URL-адреса для встраивания.
файлы : возвращает информацию о загружаемых файлах, включая формат и размер.
карта : возвращает данные о местоположении, включая координаты и адреса.
социальные сети : возвращает посты и профили из социальных платформ.
общие сведения : категория по умолчанию, которая извлекает и возвращает полное содержимое веб-страницы

Преобразование URL-адресов Reddit

При извлечении контента Reddit URL-адреса автоматически преобразуются для использования домена old.reddit.com для лучшего извлечения контента.

Ограничение скорости

Ограничение скорости на основе домена предотвращает чрезмерные запросы к одному и тому же домену в течение временного окна. Это предотвращает перегрузку целевых веб-сайтов и потенциальную блокировку IP.

Проверка кэша

Кэшированный контент веб-сайта автоматически проверяется на актуальность на основе возраста. Устаревший контент обновляется автоматически, в то время как действительный кэшированный контент быстро обслуживается.

Обработка ошибок

Сервер реализует надежную систему обработки ошибок со следующими типами исключений:

MCPServerError : Базовый класс исключений для всех ошибок сервера
ConfigurationError : Возникает, если значения конфигурации недействительны.
SearXNGConnectionError : Возникает при сбое подключения к SearXNG.
WebScrapingError : Возникает при сбое веб-скрапинга.
RateLimitExceededError : Возникает при превышении лимита скорости для домена.

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

Поиск неисправностей

Невозможно подключиться к SearXNG : убедитесь, что экземпляр SearXNG запущен и переменная среды SEARXNG_ENGINE_API_BASE_URL указывает на правильную конечную точку.
Ошибки ограничения скорости : отрегулируйте RATE_LIMIT_REQUESTS_PER_MINUTE , если у вас слишком много ошибок ограничения скорости.
Медленное извлечение контента : увеличьте значение TRAFILATURA_TIMEOUT , чтобы выделить больше времени на обработку контента на сложных страницах.
Проблемы с сетью Docker : если вы используете Docker Desktop на Windows/Mac, host.docker.internal должен разрешаться в хост-машину. В Linux вам может потребоваться использовать IP-адрес хоста.

Благодарности

Вдохновлено:

SearXNG — метапоисковая система, уважающая конфиденциальность
Trafilatura — инструмент для извлечения текста из веб-страниц
ihor-sokoliuk/mcp-searxng — Оригинальный MCP-сервер для SearXNG
nnaoycurt ( Лучший инструмент веб-поиска )
@bwoodruff2021 ( инструмент GetTimeDate )

MCP SearXNG Enhanced