searxng-mcp

모델이 볼 수 있는 출력은 짧게 유지하고, 전체 결과 페이로드는 숨겨진 메타데이터에 보존하며, 로컬 stdio 클라이언트와 배포된 streamable-http 사용을 모두 지원하는 SearXNG용 MCP 서버입니다.

제공 기능

• search: _meta에 전체 원시 페이로드가 포함된 간결한 웹 검색

• search_many: 병렬 팬아웃, 중복 제거 및 병합된 순위 지정

• search_and_fetch: 한 번의 호출로 검색 및 소스 추출

• research: 배치 가져오기 및 병합된 소스를 사용한 다중 쿼리 검색

• fetch_url: 인용이 포함된 읽기 쉬운 페이지 추출

• fetch_many: 캐싱을 사용한 병렬 URL 추출

• health: 백엔드, 캐시 및 렌더링 상태 확인

이 서버는 가볍게 설계되었습니다. 검색 작업은 SearXNG가 수행하며, searxng-mcp는 도구 구성, 캐싱, 추출 및 전송을 처리합니다.

Related MCP server: SearXNG MCP Bridge

빠른 시작

체크아웃에서 설치

uv sync
uv run searxng-mcp

uvx로 설치

searxng-mcp는 이 저장소에서 배포됩니다(PyPI 릴리스 없음). 가장 빠른 방법은 다음과 같습니다:

uvx --from git+https://github.com/88plug/searxng-mcp searxng-mcp

렌더링된 가져오기는 기본 설치에 포함되어 있습니다. 호스트에 이미 Chromium이나 Chrome이 있는 경우 searxng-mcp가 이를 사용합니다. 그렇지 않은 경우 첫 번째 렌더링된 가져오기가 사용자 캐시에 Playwright Chromium을 자동으로 부트스트랩합니다.

Docker로 실행

docker build -t searxng-mcp .
docker run --rm -p 8811:8811 --add-host=host.docker.internal:host-gateway \
  -e SEARXNG_MCP_BASE_URL=http://host.docker.internal:8890 \
  searxng-mcp

Claude Desktop 예시

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/88plug/searxng-mcp", "searxng-mcp"],
      "env": {
        "SEARXNG_MCP_BASE_URL": "http://127.0.0.1:8890",
        "SEARXNG_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

배포 모드

로컬 stdio

데스크톱 클라이언트 및 개인 워크플로우에 사용하세요. 가장 간단하고 안전한 모드입니다.

SEARXNG_MCP_TRANSPORT=stdio uv run searxng-mcp

스트리밍 가능한 HTTP

개인 서비스, 팀 배포 또는 리버스 프록시된 내부 엔드포인트에 사용하세요.

SEARXNG_MCP_TRANSPORT=streamable-http uv run searxng-mcp --host 0.0.0.0 --port 8811

강화된 Docker 및 Compose

장기 실행되는 자체 호스팅 서비스의 경우, 강화된 컨테이너 변형과 제공된 Compose 스택을 사용하세요.

docker build -f Dockerfile.prod -t searxng-mcp:prod .
cp docker-compose.env.example .env
docker compose up --build -d

보안 및 신뢰

이 프로젝트는 로컬 및 신뢰할 수 있는 네트워크 환경에서 사용하기에 안전합니다. 공개 인터넷 서비스로 바로 사용할 수 있는 형태는 아닙니다.

• fetch_url 및 fetch_many는 클라이언트가 제공한 임의의 URL을 가져올 수 있습니다.

• 렌더링된 추출은 신뢰할 수 없는 페이지에 대해 Chromium을 실행할 수 있습니다.

• streamable-http는 공유 배포 시 인증 또는 리버스 프록시 뒤에 배치해야 합니다.

• SEARXNG_MCP_FETCH_VERIFY_TLS=0은 개인 또는 자체 서명된 백엔드 설정 전용입니다.

HTTP 전송을 노출하는 경우, 내부 서비스처럼 취급하고 SSRF가 가능한 모든 도구에 기대하는 제어 장치를 추가하십시오.

이 프로젝트가 존재하는 이유

• 모델이 볼 수 있는 출력은 간결하게 유지하고, 전체 세부 정보는 숨겨진 메타데이터에 보존

• 병렬 검색 및 가져오기 팬아웃을 통한 더 빠른 연구 워크플로우

• 추가 설치 플래그 없이 JS가 많은 페이지에 대한 렌더링된 추출

• 자체 SearXNG 기반 MCP 서버를 원하는 사용자를 위한 자체 호스팅 배포

MCP 인터페이스

• searxng://config: 현재 설정, 전송 모드 및 렌더링 지원 노출

• searxng://guide: 사용 가능한 도구와 사용 시기 요약

• quick_lookup, deep_research, research_workflow: 프롬프트 인터페이스를 지원하는 클라이언트를 위한 선택적 호환성 프롬프트

환경 변수

주요 변수:

• SEARXNG_MCP_BASE_URL: SearXNG 기본 URL, 기본값 http://127.0.0.1:8890

• SEARXNG_MCP_FALLBACK_BASE_URLS: 선택적인 쉼표로 구분된 대체 SearXNG 인스턴스

• SEARXNG_MCP_TRANSPORT: stdio, streamable-http 또는 sse

• SEARXNG_MCP_SEARCH_TIMEOUT: 백엔드 검색 시간 제한(초)

• SEARXNG_MCP_FETCH_TIMEOUT: 가져오기 시간 제한(초)

• SEARXNG_MCP_SEARCH_CACHE_TTL: 검색 캐시 TTL(초)

• SEARXNG_MCP_FETCH_CACHE_TTL: 가져오기 캐시 TTL(초)

• SEARXNG_MCP_FETCH_VERIFY_TLS: 가져오기 시 TLS 확인을 건너뛰려면 0으로 설정

• SEARXNG_MCP_RENDER_TIMEOUT: 렌더링된 가져오기에 대한 브라우저 탐색 시간 제한

• SEARXNG_MCP_RENDER_WAIT_MS: 렌더링된 가져오기 시 DOM 콘텐츠 로드 후 추가 대기 시간

• SEARXNG_MCP_RENDER_CONCURRENCY: 동시 렌더링 가져오기 제한

• SEARXNG_MCP_RENDER_HEADLESS: 브라우저를 표시하려면 0으로 설정

• SEARXNG_MCP_RENDER_BROWSER_PATH: 명시적인 Chromium 또는 Chrome 바이너리 경로

• SEARXNG_MCP_RENDER_SANDBOX: Chromium 샌드박스를 활성화하려면 1로 설정

• SEARXNG_MCP_RENDER_BLOCK_RESOURCES: 렌더링 중 이미지, 글꼴, 스타일시트 및 미디어를 허용하려면 0으로 설정

• SEARXNG_MCP_RENDER_AUTO_FALLBACK: 자동 렌더링 폴백을 비활성화하려면 0으로 설정

• SEARXNG_MCP_RENDER_AUTO_MIN_WORDS: 자동 렌더링을 더 공격적으로 만들려면 이 값을 낮추세요

• SEARXNG_MCP_RENDER_AUTO_MIN_CHARS: 자동 렌더링을 더 공격적으로 만들려면 이 값을 낮추세요

• SEARXNG_MCP_CACHE_DIR: 캐시 디렉토리 경로

벤치마크

uv run searxng-mcp-bench --rounds 3

벤치마크 보고서:

• 원시 SearXNG 백엔드 지연 시간

• 토큰으로 볼 수 있는 검색 출력 크기

• 병합된 다중 쿼리 검색 지연 시간

• 다중 쿼리 연구 지연 시간

• 가져오기 추출 지연 시간

• 렌더링된 가져오기 지연 시간

• 배치 가져오기 추출 지연 시간

• 렌더링된 배치 가져오기 지연 시간

문서

• 문서 사이트 개요

• 시작하기

• 배포

• 보안

• 도구 참조

• 클라이언트 구성

• 비교

• 변경 로그

• SearXNG 문서

빌드 및 테스트

uv sync --all-groups
uv run pytest -q
uv run python -m compileall src
uv run mkdocs build --strict

의존성 유지 관리

수동 확인:

uv lock --upgrade --dry-run
uvx --from pip-audit pip-audit

자동 확인:

• uv 의존성 및 GitHub Actions에 대한 주간 Dependabot PR

• 취약점 스캔 및 업그레이드 드라이 런을 위한 주간 Dependency Health 워크플로우