Сервер SearXNG MCP Bridge

Это сервер протокола контекста модели (MCP), который выступает в качестве моста к экземпляру SearXNG. Он позволяет совместимым клиентам выполнять поиск с использованием настроенного экземпляра SearXNG через инструменты MCP.

Требования

• Node.js 25.x

• npm 11.x или новее

Related MCP server: searxng-mcp

Быстрый старт (использование через npm)

1. Настройте экземпляр SearXNG:

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng

2. Установите и запустите MCP-мост

   По умолчанию (STDIO, без изменений):

   # Run directly with npx (default - stdio transport)
   npx -y @nitish-raj/searxng-mcp-bridge

   Опционально: запуск в качестве HTTP-сервера (новая функция, по выбору)

    # Using env variables (recommended)
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   
   
   # Or run the built bundle
   TRANSPORT=http node build/index.js

3. Настройте файл конфигурации MCP (stdio / устаревшие клиенты) Добавьте в файл настроек MCP (например, ~/.vscode-server/.../mcp_settings.json):

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": [
          "-y",
          "@nitish-raj/searxng-mcp-bridge"
          ],
          "env": {
            "SEARXNG_INSTANCE_URL": "http://localhost:8080"
          },
         "disabled": false
       }
     }
   }

HTTP-конфигурация: Установите TRANSPORT=http, чтобы запустить мост через HTTP вместо stdio. Режим транспорта можно настроить с помощью переменных окружения.

Функции

• Инструмент поиска: Выполнение веб-поиска с использованием SearXNG с настраиваемыми параметрами

• Проверка работоспособности: Мониторинг подключения и производительности экземпляра SearXNG

• Двойной транспорт: Поддержка как STDIO (по умолчанию), так и HTTP-транспортов

• Управление сессиями: HTTP-транспорт включает соединения на основе сессий

• Поддержка CORS: Правильные заголовки cross-origin для интеграции с веб-клиентами

• Ограничение частоты запросов: Встроенная защита от чрезмерного количества запросов (режим HTTP)

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

• SEARXNG_INSTANCE_URL — ОБЯЗАТЕЛЬНО. Полный URL экземпляра SearXNG (например, http://localhost:8080).

• TRANSPORT — Протокол транспорта: stdio (по умолчанию) или http

• PORT — Порт HTTP-сервера. По умолчанию: 3000 (используйте 3002 для разработки)

• HOST — Адрес привязки сервера. По умолчанию: 127.0.0.1 (используйте 0.0.0.0 для контейнеров)

• CORS_ORIGIN — Список разрешенных источников для CORS, разделенных запятыми. По умолчанию: localhost:3002 (разработка) или * (продакшн)

• MCP_HTTP_BEARER — Опциональный токен bearer для HTTP-аутентификации Функции HTTP-транспорта:

• Управление сессиями с помощью заголовков mcp-session-id

• Безопасный CORS с проверкой белого списка источников

• Ограничение частоты запросов (100 запросов в минуту на IP)

• Опциональная bearer-аутентификация через MCP_HTTP_BEARER

• Защита от DNS-ребиндинга

Примечания по безопасности:

• CORS использует безопасный белый список в режиме разработки (только localhost:3002)

• В продакшене отражаются конкретные источники для запросов с учетными данными (соответствие CORS)

• Установите CORS_ORIGIN для настройки разрешенных источников под ваш случай использования

• Установите TRANSPORT=stdio для возврата в режим stdio

HTTP-транспорт

HTTP-транспорт реализует спецификацию MCP Streamable HTTP (2025-03-26) со следующими конечными точками:

Конечные точки MCP:

• POST /mcp - Отправка запросов MCP

• GET /mcp - Server-Sent Events для уведомлений

• DELETE /mcp - Завершение сессий

• OPTIONS /mcp - Предварительные запросы CORS

Системные конечные точки:

• GET /healthz - Проверка работоспособности и статуса

Тестовая HTTP-конечная точка:

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Возвращает JSON-RPC ответ со списком доступных инструментов (search и health_check).

Docker

Dockerfile открывает порт 8081 для HTTP-транспорта. Чтобы запустить контейнер и разрешить HTTP-доступ:

# Build (example)
docker build -t searxng-mcp-bridge .

# Run mapping port 8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# To run HTTP transport inside container:
 docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

Примечание: при контейнеризации установите HOST=0.0.0.0 или используйте стандартное сопоставление портов.

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

Клиенты STDIO: Используйте инструмент без изменений — настройки менять не нужно.

HTTP-клиенты: Подключитесь к http://localhost:3002/mcp (порт для разработки) и отправляйте JSON-RPC запросы MCP.

Разработка

• npm install: Установка зависимостей.

• npm run build: Компиляция TypeScript в JavaScript.

• npm run watch: Отслеживание изменений и автоматическая пересборка.

• npm run inspector: Запуск инспектора MCP для тестирования сервера.

• npm run start:http: Запуск сервера в режиме HTTP-потока на localhost:3002.

Миграция и совместимость

Обратная совместимость:

• STDIO остается транспортом по умолчанию — существующим пользователям ничего менять не нужно

• Все имена инструментов, параметры и ответы остаются без изменений

• Конфигурация осуществляется по выбору через переменные окружения

Миграция на HTTP:

• Установите TRANSPORT=http для включения HTTP-транспорта

• Настройте PORT и HOST по мере необходимости

• Обновите клиент для использования HTTP-конечной точки вместо stdio

Откат:

• Установите TRANSPORT=stdio или удалите переменную для возврата к stdio