SearXNG MCP 서버

SearXNG 인스턴스와 통합하여 웹 검색 기능을 제공하는 MCP(Model Context Protocol) 서버입니다.

기능

• 웹 검색: 여러 엔진에서 강력한 통합 검색을 수행합니다.

• 검색: 사용 가능한 카테고리와 엔진을 프로그래밍 방식으로 검색합니다.

• 상태 비저장 HTTP: 모든 표준 JSON-RPC 클라이언트와 호환됩니다.

• 유연한 구성: 환경 변수 및 명령줄 인수를 지원합니다.

MCP 서버와 함께 SearXNG를 실행하기 위한 compose.yml 예시

services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - 8080:8080
    volumes:
      - ./searxng/etc/:/etc/searxng/
      - ./searxng/data/:/var/cache/searxng/
    restart: always

  searxng-mcp:
    image: ghcr.io/aicrafted/searxng-mcp:latest
    restart: unless-stopped
    depends_on:
      # Ensure SearXNG starts before the MCP server
      - searxng
    environment:
      SEARXNG_URL: http://searxng:8080
      MCP_HOST: 0.0.0.0
      MCP_PORT: 32123
      MCP_TRANSPORT: "http"
    ports:
      - "32123:32123"

MCP 클라이언트 구성

HTTP 전송 (권장)

{
  "mcpServers": {
    "searxng": {
      "type": "http",
      "url": "http://localhost:32123/mcp"
    }
  }
}

SSE 전송

{
  "mcpServers": {
    "searxng": {
      "type": "sse",
      "url": "http://localhost:32123/sse"
    }
  }
}

참고: SSE 전송은 /mcp가 아닌 /sse 엔드포인트를 사용합니다. HTTP 전송은 /mcp를 사용합니다.

소스에서 실행하기 위한 필수 조건

• Python 3.10+

• 실행 중인 SearXNG 인스턴스.

설치

1. 저장소를 복제하고 해당 디렉토리로 이동합니다.

2. 종속성을 설치합니다:

   pip install -r requirements.txt

3. .env 파일을 설정합니다 (선택 사항):

   SEARXNG_URL=http://your-searxng-instance:8080
   MCP_PORT=32123
   MCP_HOST=127.0.0.1

사용법

uv 또는 표준 python을 사용하여 서버를 실행합니다:

python searxng_mcp.py --transport http --port 32123 --searxng http://searx.lan

Docker로 실행

1. 이미지 빌드:

   docker build -t searxng-mcp .

2. 컨테이너 실행:

   docker run -d \
     -p 32123:32123 \
     -e SEARXNG_URL=http://your-searxng-instance:8080 \
     --name searxng-mcp \
     searxng-mcp

전송 옵션

• stdio: 표준 입출력 (일부 MCP 클라이언트의 기본값).

• http: 상태 비저장 HTTP (streamable-http).

• sse: 서버 전송 이벤트 (Server-Sent Events).

검색 기능 가이드

SearXNG는 다양한 소스에서 결과를 집계합니다. 이 가이드는 web_search 도구를 통해 사용할 수 있는 기능을 설명합니다.

검색 카테고리

카테고리는 콘텐츠 유형별로 검색을 구체화하는 데 도움이 됩니다. categories 매개변수(쉼표로 구분)에 이를 사용하세요.

지원되는 엔진

SearXNG는 130개 이상의 엔진을 쿼리할 수 있습니다. 구성된 엔진에는 일반적으로 다음이 포함됩니다:

• 웹: Google, Brave, DuckDuckGo, Qwant, Startpage

• 지식: Wikipedia, Wikidata

• 개발: GitHub, StackOverflow, PyPI

• 소셜: Reddit, Twitter/X

고급 검색 매개변수

• categories: 특정 유형별로 필터링 (예: news,it).

• engines: 특정 엔진 강제 지정 (예: google,wikipedia).

• language: 검색 언어 지정 (예: en, es, fr).

• pageno: 여러 페이지의 결과 탐색.

• time_range: 날짜별 필터링 (day, month, year).

• safesearch: 콘텐츠 필터링 제어 (0=없음, 1=보통, 2=엄격).

프로그래밍 방식의 검색

web_search_info 도구를 사용하여 인스턴스에서 활성화된 카테고리 및 엔진 목록을 동적으로 검색하세요.

Windows 문제 해결

Docker 컨테이너 실행 중 localhost에 연결할 수 없음

증상: http://localhost:<port>/가 연결 거부 또는 잘못된 서비스로 연결되지만, 컨테이너 내부에서 curl은 정상적으로 작동함.

근본 원인: WSL2 포트 릴레이 고스트

WSL2는 wslrelay.exe를 사용하여 Linux VM에서 Windows 호스트로 포트를 자동으로 전달합니다. WSL 내부의 프로세스가 포트에서 수신 대기하면, WSL은 Windows 측의 [::1]:<port>(IPv6 루프백)에 바인딩된 릴레이를 생성합니다.

해당 WSL 프로세스가 중지되면 wslrelay.exe는 종종 포트를 해제하지 않습니다. 릴레이 항목은 [::1]:<port>에서 좀비 리스너로 계속 살아 있습니다.

나중에 Docker가 컨테이너를 동일한 호스트 포트에 매핑하면 0.0.0.0:<port>에 올바르게 바인딩되지만, [::1]:<port>는 이미 오래된 릴레이에 의해 점유된 상태입니다.

Windows에서 localhost는 먼저 ::1(IPv6)로 확인됩니다. 따라서 브라우저와 curl 요청이 localhost:<port>로 전달되면 Docker 컨테이너 대신 죽은 wslrelay.exe 항목에 도달하여 연결 오류나 예상치 못한 응답이 발생합니다.

명시적 IPv4 주소 127.0.0.1:<port>를 통해 연결하면 릴레이를 우회하여 Docker에 올바르게 도달합니다.

진단 방법:

# Check what is listening on the port
netstat -ano | findstr :<port>

# Identify the processes
Get-Process -Id <pid1>,<pid2> | Select-Object Id,Name

동일한 포트에 대해 com.docker.backend가 소유한 항목과 wslrelay가 소유한 항목 등 두 개의 항목이 보이면 이것이 문제입니다.

해결 방법:

영구적인 수정:

wsl --shutdown 후 Docker 컨테이너를 다시 시작하세요. 릴레이가 더 이상 존재하지 않게 되며, WSL 내부에서 동일한 포트가 다시 사용되기 전까지 localhost:<port>가 정상적으로 작동합니다.

예방:

WSL과 Docker에서 동일한 포트로 서비스를 정기적으로 실행하는 경우 다음 중 하나를 선호하세요:

• 해당 서비스에는 항상 Docker를 사용하고 WSL을 직접 사용하지 마세요.

• WSL 개발 인스턴스와 Docker 프로덕션 인스턴스에 서로 다른 포트를 사용하세요.

• docker-compose.yml에 127.0.0.1:<port>:<port> 명시적 바인딩을 추가하여 IPv4를 강제하세요.

관련 항목

• WSL2 네트워킹 문서

• WSL GitHub 이슈 트래커: wslrelay port leak 검색