🔍 SearXNG MCP 서버

AI 어시스턴트를 위한 개인정보 보호 중심 웹 검색 — 운영자가 관리하거나 신뢰할 수 있는 SearXNG 인스턴스를 Claude, Cursor 등과 함께 사용하세요.

SearXNG API를 통합하여 AI 어시스턴트에 웹 검색 기능을 제공하는 MCP 서버입니다.

✨ GitHub MCP Registry에 등재되었습니다.

빠른 시작

MCP 클라이언트 구성(예: claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": ["-y", "mcp-searxng"],
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

YOUR_SEARXNG_INSTANCE_URL을 본인의 SearXNG 인스턴스 URL(예: https://searxng.example.com)로 바꾸세요. 상호 교체 가능한 복제본을 세미콜론으로 구분된 목록으로 제공할 수도 있습니다(예: https://one.example.com;https://two.example.com).

검증된 Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, Windsurf, Cline 및 OpenCode 레시피는 MCP 클라이언트 구성 쿡북을 참조하세요.

검색, 소스 검증, 주장 교차 확인 및 증거 인용을 위한 경계가 있는 클라이언트 중립적 방법은 증거 중심 연구 워크플로를 참조하세요.

측정된 MCP 프로세스 CPU 및 메모리 시작 지점은 측정된 배포 프로필을 참조하세요.

Related MCP server: SearXNG MCP Server

기능

• 웹 검색: 페이지네이션, 시간 범위/언어/세이프서치 필터, 관련성 필터(min_score), 호출별(response_format) 또는 운영자 기본값(SEARXNG_DEFAULT_RESPONSE_FORMAT)으로 선택되는 서식 텍스트 또는 원시 JSON 출력을 지원하는 일반, 뉴스 및 기사 검색.

• 인스턴스 장애 조치 및 팬아웃: SEARXNG_URL에 상호 교체 가능한 SearXNG 복제본을 구성하세요. 기본적으로 검색은 순서대로 장애 조치되며, SEARXNG_FANOUT을 사용하면 모든 정상 복제본에 병렬로 쿼리하고 결과를 병합합니다.

• 직접 답변 및 메타데이터: 텍스트 결과는 결과 목록 앞에 SearXNG 답변, 수정 제안, 추천 검색어 및 인포박스를 표시합니다.

• 검색 추천: /autocompleter 엔드포인트를 통한 쿼리 자동 완성.

• 인스턴스 기능 탐색: /config에서 구성된 카테고리, 엔진, 기본값, 로케일 및 플러그인을 검사합니다.

• URL 콘텐츠 읽기: 콘텐츠 유형을 인식하는 Markdown 변환(제한된 PDF 텍스트 추출 포함)과 페이지네이션, 섹션 필터링, 문단 범위 및 제목 추출을 지원합니다.

• 브라우저 솔버 지원: 정적 URL 검증과 HEAD 크기 사전 점검을 통과한 각 캐시되지 않은 URL에 대해 선택적으로 FlareSolverr, Byparr 또는 둘 모두에서 브라우저 세션을 획득한 후 반환된 사용자 에이전트와 범위가 제한된 쿠키를 경계가 있는 URL 리더를 통해 재생합니다. 이중 공급자 모드에서는 FlareSolverr이 항상 기본이며 Byparr은 기본 공급자가 사용 중이거나 일시적으로 사용 불가능한 경우에만 시도됩니다. FlareSolverr 3.5.0 및 Byparr 2.1.0은 2026-07-30에 검증되었습니다.

• 지능형 캐싱: 검색 결과와 URL 콘텐츠 모두 구성 가능한 TTL과 LFU(최소 빈도 사용) 축출 방식으로 메모리에 캐시되어 중복 요청을 줄입니다.

• SSRF 보호: web_url_read는 모든 전송 모드에서 기본적으로 개인/내부 URL 및 리디렉션을 차단합니다.

• HTTP 전송: 선택적 MCP SDK v2 Streamable HTTP 모드로, 강화 옵션, 속도 제한 및 서버리스 또는 수평 확장 배포를 위한 경계가 있는 무상태 호환성을 제공합니다. 최신 2026-07-28 요청과 유지되는 레거시 클라이언트는 동일한 도구 및 리소스 표면을 공유합니다.

• HTML 폴백: format=json을 거부하는 공용 인스턴스에 대해 HTML 페이지에서 결과를 선택적으로 파싱합니다.

• 라이트 도구 모드: 작은 컨텍스트 창을 가진 로컬 모델을 위한 최소 도구 스키마.

• 프록시 지원: 검색 및 URL 리더 트래픽에 대한 전역 또는 도구별 HTTP/HTTPS 프록시.

검증된 linux/amd64 이미지는 다중 아키텍처 매니페스트 ghcr.io/flaresolverr/flaresolverr:v3.5.0@sha256:139dfee1c6f89249c8d665d1333a42e8ec74ec0a86bc6bb1c8461e10d3a66a47 및 ghcr.io/thephaseless/byparr:2.1.0@sha256:01a46a2865d9a6db5eb8ead04ec0dd33b8fbe233e8565ae70b50d4cc0af4cfb0에서 가져왔습니다. 클라이언트 취소는 로컬 작업을 신속히 중단하지만, 원격 브라우저는 HTTP 클라이언트 연결이 끊긴 후에도 구성된 공급자 타임아웃까지 계속 실행될 수 있습니다. 브라우저 솔버 검증을 참조하세요.

왜 mcp-searxng인가?

2026-07-29 기준, 아래 기능 비교는 공식 Brave MCP, Exa MCP 및 Firecrawl MCP 프로젝트를 반영합니다. "페이지네이션"은 노출된 페이지 또는 오프셋 제어를 의미합니다. "자체 호스팅"은 검색 서비스를 본인의 통제 하에 실행할 수 있음을 의미합니다. "무료 / API 키 불필요"는 이 MCP 서버가 유료 검색 공급업체 API 키를 요구하지 않음을 의미합니다. 여전히 기본 SearXNG 인스턴스를 운영하거나 선택해야 합니다.

개인정보 보호는 SearXNG 배포 방식에 따라 달라집니다. 운영자가 관리하는 인스턴스는 제3자 검색 운영자를 신뢰하지 않아도 되지만, 공용 인스턴스는 쿼리를 수신하고 이를 기록할 수 있습니다. SearXNG와 이 MCP 통합은 그 자체로 익명성을 제공하지 않습니다.

작동 방식

mcp-searxng는 독립형 MCP 서버입니다. 즉, AI 어시스턴트가 웹 검색을 위해 연결하는 별도의 Node.js 프로세스입니다. HTTP JSON API를 통해 하나의 SearXNG 인스턴스 또는 세미콜론으로 구분된 상호 교체 가능한 SearXNG 복제본 목록을 쿼리합니다.

SearXNG 플러그인이 아님: 이 프로젝트는 네이티브 SearXNG 플러그인으로 설치할 수 없습니다. SEARXNG_URL을 설정하여 기존 SearXNG 인스턴스 또는 상호 교체 가능한 복제본 목록을 가리키기만 하면 됩니다.

AI Assistant (e.g. Claude)
        │  MCP protocol
        ▼
  mcp-searxng  (this project — Node.js process)
        │  HTTP JSON API  (SEARXNG_URL)
        ▼
  SearXNG instance(s)

SearXNG 배포, 구성 및 문제 해결에 대해서는 자체 호스팅 SearXNG를 mcp-searxng과 함께 운영하기를 참조하세요.

도구

• searxng_web_search

  • 페이지네이션을 지원하는 웹 검색 실행

  • 입력:

    • query (문자열): 검색어. 이 문자열은 외부 검색 서비스에 전달됩니다.

    • pageno (숫자, 선택): 검색 페이지 번호, 1부터 시작 (기본값 1)

    • time_range (문자열, 선택): 시간 범위로 결과 필터링 - "day", "week", "month", "year" 중 하나 (기본값: 없음)

    • language (문자열, 선택): 결과의 언어 코드 (예: "en", "fr", "de") 또는 "all" (기본값: "all")

    • safesearch (문자열 열거형, 선택): 세이프서치 필터 수준, "0" (없음), "1" (보통), "2" (엄격) 중 하나. 이전 버전과의 호환성을 위해 기존 숫자 값 0, 1, 2도 계속 허용됩니다. (기본값: 인스턴스 설정)

    • min_score (숫자, 선택): 0.0에서 1.0 사이의 최소 관련성 점수. 이 점수 미만의 결과는 필터링됩니다.

    • num_results (숫자, 선택): 반환할 최대 결과 수, 1에서 20까지. SEARXNG_MAX_RESULTS가 연산자 상한으로 적용됩니다.

    • categories (문자열, 선택): 쉼표로 구분된 SearXNG 카테고리 (예: "news", "it,science"). 실시간 /config 기능은 도달 가능한 인스턴스 전체에서 집계됩니다. 일관된 다중 인스턴스 결과를 위해 searxng_instance_info의 categories.common을 선호합니다. 알려진 값은 대소문자를 구분하지 않고 정규화되어 전달됩니다. 알 수 없는 값은 SearXNG가 무시하거나 처리할 수 있도록 공백이 제거된 채 전달됩니다. /config를 사용할 수 없으면 값은 경고와 함께 그대로 전달됩니다. 생략하면 각 인스턴스는 서버 측 기본값을 사용합니다.

    • engines (문자열, 선택): 쉼표로 구분된 SearXNG 엔진 이름 (예: "google,bing,ddg", "semantic scholar"). 실시간 /config 기능은 도달 가능한 인스턴스 전체에서 집계됩니다. 일관된 다중 인스턴스 결과를 위해 searxng_instance_info의 engines.common.enabled를 선호합니다. 알려진 값은 기본적으로 비활성화된 엔진을 포함하여 공백을 제거하고 대소문자를 구분하지 않고 정규화됩니다. 알 수 없는 값은 SearXNG가 무시하거나 처리할 수 있도록 공백이 제거된 채 전달됩니다. /config를 사용할 수 없으면 값은 경고와 함께 그대로 전달됩니다. 생략하면 각 인스턴스는 서버 측 기본값을 사용합니다.

    • response_format (문자열, 선택): 응답 형식. 에이전트가 읽을 수 있는 형식의 출력에는 "text", 필터링/슬라이스된 results가 포함된 원시 SearXNG JSON에는 "json". 생략하면 SEARXNG_DEFAULT_RESPONSE_FORMAT이 적용됩니다. 설정되지 않았거나 유효하지 않으면 text가 사용됩니다. 명시적인 response_format은 항상 우선합니다.

    • result_detail (문자열, 선택): "full"(기본값)은 SearXNG 메타데이터, 경고, 출처, 답변, 정보 상자, 수정 사항 및 제안을 보존합니다. "compact"는 모든 결과에 대해 제목, URL, 설명/콘텐츠 스니펫만 반환합니다. 컴팩트 JSON은 정확히 title, url, content 키를 사용합니다. 이러한 연구 신호가 중요할 때는 full을 사용하세요.

    • 명시적으로 response_format=text를 보내거나 자동으로 주입하는 클라이언트는 계속해서 연산자 기본값을 재정의합니다. JSON 구성 후에도 생략된 호출이 여전히 텍스트를 반환하는 경우 MCP 클라이언트가 내보낸 인수를 검사하세요.

  마이그레이션: 컴팩트 텍스트는 결과당 정확히 세 줄이며 캐시 주석이나 머리말이 없습니다. 관련성 점수나 검색 메타데이터를 기대하는 줄 파서는 result_detail="full"을 요청하도록 업데이트하세요(또는 컴팩트의 세 줄 레코드 허용).

  컴팩트는 의도적으로 경고, 출처 및 기타 모든 검색 신호를 억제합니다. 전체 텍스트는 고정된 순서로 유효한 선택적 줄을 추가할 수 있습니다: 점수, 엔진, 카테고리, 게시 날짜, 썸네일, 이미지 소스. 잘못된 선택적 메타데이터는 생략됩니다. 텍스트 필드는 한 줄로 정규화됩니다. SEARXNG_MAX_RESULT_CHARS는 컴팩트 및 전체 텍스트/JSON 응답에서 결과 콘텐츠를 잘라냅니다. 여기에는 이미 변수를 설정한 기존 사용자의 전체 JSON도 포함됩니다. 컴팩트 텍스트는 상한을 적용하기 전에 줄 구분 기호를 정규화하는 반면, JSON은 원래 문자열 값을 제한합니다.

  SEARXNG_LITE_TOOLS=true인 경우 Lite 스키마는 쿼리 전용으로 유지되지만 response_format 및 result_detail과 같은 명시적으로 제공된 선택적 재정의는 여전히 검증되고 존중됩니다.

• searxng_search_suggestions

  • 검색 쿼리 구체화를 위한 자동 완성 제안 가져오기

  • 입력:

    • query (문자열): 자동 완성할 부분 또는 전체 쿼리.

    • language (문자열, 선택): 제안의 언어 코드 (예: "en", "fr", "de") 또는 "all" (기본값: "all")

• searxng_instance_info

  • 도달 가능한 구성된 SearXNG 인스턴스에서 집계된 카테고리를 발견하고, 선택적으로 엔진 이름을 포함하며, 기본 인스턴스의 기본값, 로케일 및 플러그인을 검사합니다. 카테고리(및 요청 시 엔진)는 모든 도달 가능한 인스턴스에 있는 common 값과 하나 이상의 도달 가능한 인스턴스에 있는 available 값을 보고합니다.

  • 입력:

    • includeEngines (부울, 선택): 응답에 활성화된 엔진 이름을 포함합니다. (기본값: false)

    • includeDisabled (부울, 선택): includeEngines가 true일 때 비활성화된 엔진 이름을 포함합니다. (기본값: false)

    • category (문자열, 선택): 카테고리와 엔진을 단일 카테고리 이름으로 필터링합니다.

    • refresh (부울, 선택): 프로세스 캐시를 우회하고 새 /config 데이터를 가져옵니다. (기본값: false)

• web_url_read

  • 콘텐츠 유형 인식 처리 및 고급 추출 옵션을 사용하여 URL 콘텐츠를 마크다운으로 읽기

  • 지원되는 읽을 수 있는 콘텐츠:

    • HTML (text/html, application/xhtml+xml)은 마크다운으로 변환됩니다.

    • JSON (application/json, *+json)은 펜스 블록에 예쁘게 인쇄됩니다.

    • 일반 텍스트, YAML, TOML, XML 및 기타 안전한 명시적 text/* 응답은 읽을 수 있는 펜스 텍스트로 반환됩니다.

    • PDF (application/pdf) 텍스트는 최대 500페이지 문서에 대해 리소스 제한 작업자에서 추출됩니다.

    • 누락되거나 일반적인 콘텐츠 유형은 기존 크기 제한 내에서 읽습니다. 비이진 본문은 호환성을 위해 HTML-마크다운 경로를 계속 통과합니다.

  • PDF 입력 및 추출된 텍스트는 각각 URL_READ_MAX_CONTENT_LENGTH_BYTES와 16 MiB 중 낮은 값으로 제한됩니다. OCR은 지원되지 않으며, 스캔/이미지 전용 또는 암호로 보호된 PDF는 짧은 설명을 반환합니다.

  • PDF로 선언된 응답은 %PDF- 시그니처로 시작해야 합니다. 불일치는 일반적으로 잘못된 콘텐츠 유형으로 제공되는 중간 또는 오류 페이지를 나타냅니다.

  • PDF 파싱은 응답 본문이 다운로드된 후 별도의 30초 작업자 예산을 갖습니다. 직접 경로에서 네트워크 가져오기 및 파싱은 구성된 가져오기 예산 + 30초를 최대로 사용합니다. 구성된 브라우저 해결자 사전 검사 및 획득 시간은 추가입니다.

  • MCP 프로세스당 최대 두 개의 PDF 추출이 동시에 실행됩니다. 대기열이 없습니다. 추가 동시 읽기는 사용 중 메시지를 반환하며 재시도할 수 있습니다.

  • 기타 이진, 미디어, 아카이브 및 octet-stream 다운로드는 원시 바이트를 반환하는 대신 짧은 힌트와 함께 의도적으로 거부됩니다.

  • FLARESOLVERR_URL 또는 BYPARR_URL이 구성된 경우, 캐시되지 않은 URL은 mcp-searxng가 브라우저 세션 획득을 시도하기 전에 HEAD 크기 사전 검사로 검증되고 확인됩니다. 둘 다 설정된 경우 FlareSolverr가 먼저 시도되고 Byparr은 사용 중인 슬롯, 네트워크/시간 초과 실패, HTTP 408/429/5xx 또는 잘못된/과도한 응답 후에만 시도됩니다. 지속적인 공급자 4xx, 취소, 솔루션 호스트 검증 실패 및 해결된 비-2xx 대상 상태는 체인을 중지합니다. 구성된 모든 공급자가 사용 중이거나 사용할 수 없으면 캐시되지 않은 직접 가져오기가 한 번 실행됩니다. 각 시도된 공급자는 원래 대상 URL을 받습니다. 챌린지 성공은 보장되지 않습니다.

  • 기본 제한에서 이중 공급자 모드는 초기 HEAD 사전 검사, 두 솔버 시도(응답 유예 포함) 및 최종 직접 가져오기에서 최대 150초의 가산 최대값을 갖습니다.

  • 입력:

    • url (문자열): 가져와서 처리할 URL

    • startChar (숫자, 선택): 콘텐츠 추출 시작 문자 위치 (기본값: 0)

    • maxLength (숫자, 선택): 반환할 최대 문자 수

    • section (문자열, 선택): 특정 제목 아래의 콘텐츠 추출 (제목 텍스트 검색)

    • paragraphRange (문자열, 선택): 특정 단락 범위 반환 (예: '1-5', '3', '10-')

    • readHeadings (부울, 선택): 전체 콘텐츠 대신 제목 목록만 반환

설치

Node.js 22 이상이 필요합니다.

npm install -g mcp-searxng

{
  "mcpServers": {
    "searxng": {
      "command": "mcp-searxng",
      "env": {
        "SEARXNG_URL": "YOUR_SEARXNG_INSTANCE_URL"
      }
    }
  }
}

사전 빌드 이미지:

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"
      }
    }
  }
}

추가 환경 변수를 전달하려면 args에 -e VAR_NAME을 추가하고 env에 변수를 추가하세요. 브라우저 솔버 통합의 경우 FLARESOLVERR_URL, BYPARR_URL 또는 둘 다 전달하고 구성된 서비스가 이 컨테이너에서 도달 가능한지 확인하세요. 이중 모드에는 고정된 FlareSolverr 우선 순서가 있으며 자동 역장애 조치가 없습니다. 전체 동작 및 Docker Compose 예제는 URL Reader Controls를 참조하세요.

로컬 빌드:

docker build -t mcp-searxng:latest -f Dockerfile .

위와 동일한 구성을 사용하고 isokoliuk/mcp-searxng:latest를 mcp-searxng:latest로 바꾸세요.

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}
      # Add optional variables as needed — see CONFIGURATION.md

추적되는 Compose 파일은 의도적으로 STDIO 전용이며 네트워크 포트를 게시하지 않습니다. MCP 클라이언트는 절대 Compose 파일 경로와 docker compose run --rm -T로 실행하며 docker compose up이 아닙니다. -T 플래그는 의사 TTY 할당을 방지하여 MCP JSON-RPC가 원시 표준 입력 및 출력에 유지되도록 합니다. MCP 클라이언트가 SEARXNG_URL을 제공하지 않으면 Compose는 시작 전에 실패합니다.

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"
      }
    }
  }
}

이전에 추적된 파일을 포트 8080의 HTTP 서비스로 사용했다면 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은 컨테이너 측 바인드 주소입니다. 호스트 측 포트는 루프백 전용으로 유지됩니다. 이 오버라이드에는 인증이 없으며 일시적인 단일 호스트 마이그레이션 경로일 뿐입니다. 동일한 위치의 컨테이너를 추가하거나 로컬 머신 너머로 서비스를 노출하기 전에 강화된 배포 지침을 따르세요.

기본적으로 서버는 MCP 클라이언트가 시작하는 STDIO를 사용합니다. HTTP를 대신 사용하려면 MCP_HTTP_PORT를 설정하여 mcp-searxng를 독립 프로세스로 실행하세요. 이 모드에서는 HTTP를 통해 MCP 프로토콜을 제공하며 STDIO를 사용하지 않으므로 클라이언트는 프로세스를 생성하는 대신 URL로 연결합니다.

서버 시작:

MCP_HTTP_PORT=3000 SEARXNG_URL=http://localhost:8080 mcp-searxng

또는 Docker 사용 (호스트에서 포트에 도달할 수 있도록 모든 인터페이스에 바인딩):

docker run --rm -p 3000:3000 \
  --add-host=host.docker.internal:host-gateway \
  -e MCP_HTTP_PORT=3000 -e MCP_HTTP_HOST=0.0.0.0 \
  -e SEARXNG_URL=http://host.docker.internal:8080 \
  isokoliuk/mcp-searxng:latest

--add-host 매핑을 사용하면 컨테이너가 host.docker.internal을 통해 호스트의 SearXNG 인스턴스에 도달할 수 있습니다. Docker Desktop에서는 자동으로 해결되지만 네이티브 Linux에서는 이 플래그가 필요합니다. 실제 인스턴스가 다른 곳에서 실행되는 경우 SEARXNG_URL을 해당 인스턴스로 지정하세요.

HTTP 지원 MCP 클라이언트를 URL로 /mcp 엔드포인트에 연결:

{
  "mcpServers": {
    "searxng-http": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

프로토콜 지원: HTTP와 STDIO는 최신 MCP 2026-07-28 및 유지되는 레거시 개정판 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07을 제공합니다. 최신 HTTP는 세션 없는 POST /mcp입니다. 레거시 HTTP는 기본적으로 상태 저장(POST/GET/DELETE /mcp)이거나 기존 POST 전용 무상태 모드를 사용합니다.

엔드포인트: 최신 POST /mcp; 레거시 상태 저장 기본값의 POST/GET/DELETE /mcp 또는 무상태 모드의 레거시 POST /mcp 전용; GET /health.

레거시 HTTP 클라이언트의 경우 상태 저장 세션이 기본값으로 유지됩니다. 요청 간에 메모리 내 레거시 세션을 보존할 수 없는 배포에서는 MCP_HTTP_STATELESS=true를 설정하세요. 최신 HTTP는 해당 설정과 관계없이 세션 없이 유지됩니다. 모든 무상태 POST는 새 MCP 서버와 전송을 생성하고 들어오는 세션 ID를 무시하며 동일한 POST 내에서 협상된 JSON 또는 SSE 스트림을 반환합니다. 무상태 모드는 POST 전용입니다. GET /mcp 및 DELETE /mcp는 Allow: POST와 함께 HTTP 405를 반환하며, 요청 간 구독, 재개 가능성 또는 서버-클라이언트 알림은 보존되지 않습니다.

상태 비저장 요청은 전역 및 클라이언트 IP별 동시 실행 제한과 요청 수명에 의해 제한됩니다. 기본값, 과부하 및 시간 초과 응답, 프록시 인지 공정성, 전체 호환성 계약은 CONFIGURATION.md를 참조하세요.

출처(Origin) 검증 및 업그레이드 공지: /mcp에 전달되는 모든 Origin은 모든 모드에서 검증됩니다. Origin이 없는 경우 비브라우저 클라이언트에는 유효합니다. 비강화(non-hardened) 모드에서 MCP_HTTP_ALLOWED_ORIGINS가 설정되지 않으면 정확한 HTTP/HTTPS 루프백 출처인 http://127.0.0.1, https://127.0.0.1, http://localhost, https://localhost, http://[::1], https://[::1]로 기본 설정되며, 포트가 없거나 구성된 MCP_HTTP_PORT가 있는 형태 모두 포함됩니다. 비어 있지 않은 MCP_HTTP_ALLOWED_ORIGINS는 이러한 기본값을 대체합니다. 항목은 공백이 제거되지만 그 외에는 문자 그대로 처리됩니다. 일치는 정확하고 대소문자를 구분하는 리터럴 매칭이며, 스킴과 포트를 포함합니다. 잘못된 형식, 스킴 누락, 경로 포함, 후행 슬래시, 대소문자가 다른 값은 조용히 일치하지 않으므로 수정해야 합니다. 강화 모드에서는 여전히 명시적 허용 목록이 필요하며 인증과 Host 강제 적용이 추가됩니다. /mcp에 잘못된 Origin이 있으면 파서, 인증, 속도 제한, 전송 구성 전에 고정된 비반사 403을 받습니다. /health는 MCP 403 경계 밖에 있지만 축소된 전역 CORS 허용 목록을 사용합니다. 업그레이드 전에 루프백이 아닌 Origin을 사용하는 기존 비강화 브라우저 배포는 MCP_HTTP_ALLOWED_ORIGINS를 설정해야 하며, 그렇지 않으면 고정 403을 받습니다.

테스트:

curl http://localhost:3000/health

서버는 기본적으로 127.0.0.1에 바인딩됩니다. 원격 또는 컨테이너 배포의 경우 MCP_HTTP_HOST=0.0.0.0을 설정하세요. 네트워크에 노출하기 전에 강화 모드(MCP_HTTP_HARDEN)를 활성화하고 속도 제한과 로그가 올바른 클라이언트 IP를 사용하도록 CONFIGURATION.md의 MCP_HTTP_TRUST_PROXY를 확인하세요.

구성

SEARXNG_URL은 유일한 필수 변수입니다. SearXNG 인스턴스 URL(또는 상호 교체 가능한 복제본의 세미콜론 구분 목록)로 설정하세요. 나머지는 모두 선택 사항입니다.

SEARXNG_DEFAULT_RESPONSE_FORMAT을 사용하여 검색 호출이 response_format을 생략할 때 text 또는 json을 선택하세요. 호출별 명시적 값이 여전히 우선합니다.

전체 환경 변수 참조는 CONFIGURATION.md 를 참조하세요. 인증, 장애 조치/팬아웃, 캐싱, 시간 초과, 프록시, TLS, HTTP 전송 및 강화가 포함됩니다.

문제 해결

자체 호스팅 SearXNG 구성, 직접 검증 및 문제 해결은 Operating Self-Hosted SearXNG with mcp-searxng를 참조하세요. 인스턴스를 제어하지 않는 경우 별도의 public SearXNG instance guide를 대신 사용하세요.

TLS 검사 기업 프록시 뒤에서 인증서 오류로 HTTPS 요청이 실패하는 경우 TLS / Corporate CA를 참조하세요.

SearXNG에서 403 Forbidden

SearXNG 인스턴스에서 JSON 형식이 비활성화되어 있을 가능성이 높습니다. settings.yml(일반적으로 /etc/searxng/settings.yml)을 편집하세요:

search:
  formats:
    - html
    - json

SearXNG를 다시 시작한 후(docker restart searxng) 다음을 확인하세요:

curl 'http://localhost:8080/search?q=test&format=json'

JSON 응답을 받아야 합니다. 그렇지 않은 경우 파일이 올바르게 마운트되었는지와 YAML 들여쓰기가 유효한지 확인하세요.

참고: SearXNG settings docs · discussion

JSON을 활성화할 수 없나요? (HTML 폴백)

제어할 수 없는 공용 인스턴스를 사용해야 하고 format=json을 거부하는 경우(위의 403), 서버를 편집하는 대신 옵트인 플래그를 설정하세요:

활성화하기 전에 공용 운영자의 정책과 public-instance usage guide를 검토하세요.

{
  "SEARXNG_HTML_FALLBACK": "true"
}

403/404 또는 비JSON 응답을 받는 검색은 format=json 없이 자동으로 재시도되며 일반 HTML 결과 페이지에서 파싱됩니다.

• 성공 시: 일반 결과(제목, URL, 스니펫)를 얻습니다. JSON 모드에서는 sourceFormat: "html"로 표시되고, 텍스트 모드에서는 "참고: SearXNG HTML 폴백에서 파싱된 결과입니다. 메타데이터가 제한됩니다." 줄이 추가됩니다. 관련성 점수와 엔진 이름은 HTML에서 사용할 수 없습니다.

• 실패 시: 파싱은 최선 노력(best-effort) 방식이며 인스턴스의 테마/버전에 따라 달라지므로 일부 결과가 누락되거나 부족할 수 있습니다. HTML 페이지 자체도 실패하는 경우(차단, 속도 제한(429), 인증(401) 또는 5xx) 폴백 시도의 오류가 표시되므로 검색이 조용히 빈 결과를 반환하지 않습니다. 폴백은 403/404/비JSON에서만 트리거되며 인증 또는 네트워크 오류에서는 절대 트리거되지 않습니다.

제어할 수 있는 인스턴스에서 JSON을 활성화하는 것(위)이 여전히 권장 설정입니다. 폴백은 호환성 보조 수단이지 대체 수단이 아닙니다.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT — 자세한 내용은 LICENSE를 참조하세요.