Сервер SearXNG MCP Bridge

Release

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

Требования

Node.js 25.x
npm 11.x или новее

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

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

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

Установите и запустите 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

Настройте файл конфигурации 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

SearXNG MCP Bridge