MCP SearXNG 향상

MCP SearXNG 향상된 서버

카테고리 기반 웹 검색, 웹사이트 스크래핑, 날짜/시간 도구를 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. SearXNG 및 최신 MCP 클라이언트와 원활하게 통합되도록 설계되었습니다.

특징

🔍 카테고리 지원(일반, 이미지, 비디오, 파일, 지도, 소셜 미디어)을 갖춘 SearXNG 기반 웹 검색
📄 인용 메타데이터와 자동 Reddit URL 변환을 통한 웹사이트 콘텐츠 스크래핑
💾 자동 신선도 검증 기능이 있는 인메모리 캐싱
🚦 서비스 남용을 방지하기 위한 도메인 기반 속도 제한
🕒 시간대 인식 날짜/시간 도구
⚠️ 사용자 정의 예외 유형을 통한 강력한 오류 처리
🐳 Docker화되어 환경 변수를 통해 구성 가능
⚙️ 컨테이너 재시작 간 구성 지속성

빠른 시작

필수 조건

시스템에 Docker가 설치됨
실행 중인 SearXNG 인스턴스(자체 호스팅 또는 액세스 가능한 엔드포인트)

설치 및 사용

Docker 이미지를 빌드합니다.

지엑스피1

SearXNG 인스턴스로 실행합니다(수동 Docker 실행):

docker run -i --rm --network=host \
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \
  -e DESIRED_TIMEZONE="America/New_York" \
  overtlids/mcp-searxng-enhanced:latest

이 예에서 SEARXNG_ENGINE_API_BASE_URL 명시적으로 설정되었습니다. DESIRED_TIMEZONE 또한 기본값과 일치하는 America/New_York 으로 명시적으로 설정되었습니다. docker run 명령 실행 시 -e 플래그를 사용하여 환경 변수를 지정하지 않으면 서버는 Dockerfile 에 정의된 기본값을 자동으로 사용합니다(아래 환경 변수 표 참조). 따라서 DESIRED_TIMEZONE 의 기본값을 사용하려면 -e DESIRED_TIMEZONE="America/New_York" 플래그를 생략할 수 있습니다. 그러나 SEARXNG_ENGINE_API_BASE_URL 매우 중요하며, Dockerfile 기본값( http://host.docker.internal:8080/search )이 적합하지 않은 경우 일반적으로 특정 SearXNG 인스턴스의 주소와 일치하도록 설정해야 합니다.

수동 Docker 실행에 대한 참고 사항: 이 명령은 Docker 컨테이너를 독립적으로 실행합니다. MCP 클라이언트(VS Code의 Cline 등)를 사용하여 이 서버를 관리하는 경우, 클라이언트는 자체 구성 에 정의된 설정을 사용하여 자체 컨테이너 인스턴스를 시작합니다. MCP 클라이언트가 특정 환경 변수를 사용하려면 해당 서버의 클라이언트 설정에서 해당 변수를 구성 해야 합니다 (아래 참조).

MCP 클라이언트를 구성하세요 (예: VS Code의 Cline):

MCP 클라이언트가 이 서버를 올바르게 관리하고 실행하려면 overtlids/mcp-searxng-enhanced 서버에 대한 클라이언트 설정에서 필요한 모든 환경 변수를 정의 해야 합니다 . MCP 클라이언트는 이러한 설정을 사용하여 docker run 명령을 실행합니다.

다음은 MCP 클라이언트의 JSON 설정(예: cline_mcp_settings.json ) 내에서 이 서버에 권장되는 기본 구성 입니다. 이 예제는 Dockerfile 에 정의된 기본값으로 설정된 모든 환경 변수를 명시적으로 나열합니다. 이 예제를 직접 복사하여 붙여넣은 후 필요에 따라 값을 사용자 지정할 수 있습니다.

{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}

MCP 클라이언트 구성을 위한 핵심 사항:

위의 예에서는 모든 환경 변수를 기본값으로 설정하여 Docker 컨테이너를 실행하기 위한 전체 인수 세트를 제공합니다.
설정을 사용자 지정하려면 MCP 클라이언트 구성의 args 배열에서 해당 -e "VARIABLE_NAME=value" 줄의 값을 수정하기만 하면 됩니다. 예를 들어 SEARXNG_ENGINE_API_BASE_URL 과 DESIRED_TIMEZONE 변경하려면 해당 줄을 조정하면 됩니다.
각 변수와 기본값에 대한 자세한 설명은 아래의 "환경 변수" 표를 참조하세요.
서버의 동작은 주로 이러한 환경 변수에 의해 제어됩니다. ods_config.json 파일도 설정에 영향을 미칠 수 있지만(구성 관리 참조), MCP 클라이언트에서 전달한 환경 변수가 우선합니다.

네이티브로 실행(Docker 없이)

Docker 없이 Python을 사용하여 서버를 직접 실행하려면 다음 단계를 따르세요.

1. 파이썬 설치:

이 서버에는 Python 3.9 이상이 필요합니다. Docker 이미지에 사용된 Python 3.11을 권장합니다.
python.org 에서 Python을 다운로드할 수 있습니다.

2. 저장소 복제:

GitHub에서 코드를 받으세요:
git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git cd mcp-searxng-enhanced

3. 가상 환경 생성 및 활성화(권장):

가상 환경을 사용하면 종속성을 관리하고 다른 Python 프로젝트와의 충돌을 피하는 데 도움이 됩니다.
# For Linux/macOS python3 -m venv .venv source .venv/bin/activate # For Windows (Command Prompt) python -m venv .venv .\.venv\Scripts\activate.bat # For Windows (PowerShell) python -m venv .venv .\.venv\Scripts\Activate.ps1

4. 종속성 설치:

필요한 Python 패키지를 설치하세요.
pip install -r requirements.txt
주요 종속성에는 httpx , BeautifulSoup4 , pydantic , trafilatura , python-dateutil , cachetools , zoneinfo 포함됩니다.

5. SearXNG에 액세스할 수 있는지 확인하세요.

아직 실행 중인 SearXNG 인스턴스가 필요합니다. API 기반 URL(예: http://127.0.0.1:8080/search )이 있는지 확인하세요.

6. 환경 변수 설정:

서버는 환경 변수를 통해 구성됩니다. 최소한 SEARXNG_ENGINE_API_BASE_URL 설정해야 할 가능성이 높습니다.
Linux/macOS(bash/zsh):
export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" export DESIRED_TIMEZONE="America/Los_Angeles"
Windows(명령 프롬프트):
set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" set DESIRED_TIMEZONE="America/Los_Angeles"
윈도우(PowerShell):
$env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" $env:DESIRED_TIMEZONE="America/Los_Angeles"
사용 가능한 모든 옵션은 아래 "환경 변수" 표를 참조하세요. 설정하지 않으면 스크립트 또는 ods_config.json 파일(루트 디렉터리 또는 ODS_CONFIG_PATH 에 있는 경우)의 기본값이 사용됩니다.

7. 서버를 실행합니다.

Python 스크립트를 실행합니다.
python mcp_server.py
서버가 시작되고 stdin/stdout을 통해 MCP 클라이언트 연결을 수신합니다.

8. 구성 파일( ods_config.json ):

또는 환경 변수와 함께 또는 프로젝트 루트 디렉터리(또는 ODS_CONFIG_PATH 환경 변수로 지정된 경로)에 ods_config.json 파일을 생성할 수 있습니다. 환경 변수는 항상 이 파일의 값보다 우선합니다. 예: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

환경 변수

다음 환경 변수는 서버의 동작을 제어합니다. MCP 클라이언트 구성(클라이언트 관리 서버에 권장)에서 설정하거나 Docker를 수동으로 실행할 때 설정할 수 있습니다.

변하기 쉬운	설명	기본값(Dockerfile에서)	노트
`SEARXNG_ENGINE_API_BASE_URL`	SearXNG 검색 엔드포인트	`http://host.docker.internal:8080/search`	서버 운영에 필수
`DESIRED_TIMEZONE`	날짜/시간 도구의 시간대	`America/New_York`	예: `America/Los_Angeles` . tz 데이터베이스 시간대 목록: https://en.wikipedia.org/wiki/List\_of\_tz\_database\_time\_zones
`ODS_CONFIG_PATH`	영구 구성 파일 경로	`/config/ods_config.json`	일반적으로 컨테이너 내에서 기본값으로 유지됩니다.
`RETURNED_SCRAPPED_PAGES_NO`	검색당 반환할 최대 페이지 수	`3`
`SCRAPPED_PAGES_NO`	스크래핑을 시도할 최대 페이지 수	`5`
`PAGE_CONTENT_WORDS_LIMIT`	스크래핑된 페이지당 최대 단어 수	`5000`
`CITATION_LINKS`	인용 이벤트 활성화/비활성화	`True`	`True` 또는 `False`
`MAX_IMAGE_RESULTS`	반환할 최대 이미지 결과	`10`
`MAX_VIDEO_RESULTS`	반환할 최대 비디오 결과	`10`
`MAX_FILE_RESULTS`	반환할 최대 파일 결과	`5`
`MAX_MAP_RESULTS`	반환할 최대 지도 결과	`5`
`MAX_SOCIAL_RESULTS`	최대 소셜 미디어 결과를 반환합니다	`5`
`TRAFILATURA_TIMEOUT`	콘텐츠 추출 시간 초과(초)	`15`
`SCRAPING_TIMEOUT`	HTTP 요청 시간 초과(초)	`20`
`CACHE_MAXSIZE`	캐시된 웹사이트의 최대 수	`100`
`CACHE_TTL_MINUTES`	캐시 수명(분)	`5`
`CACHE_MAX_AGE_MINUTES`	캐시된 콘텐츠의 최대 수명(분)	`30`
`RATE_LIMIT_REQUESTS_PER_MINUTE`	도메인당 분당 최대 요청 수	`10`
`RATE_LIMIT_TIMEOUT_SECONDS`	속도 제한 추적 창(초)	`60`
`IGNORED_WEBSITES`	무시할 사이트의 쉼표로 구분된 목록	`""` (비어 있는)	예: `"example.com,another.org"`

구성 관리

서버는 3계층 구성 방식을 사용합니다.

스크립트 기본값 (Python으로 하드코딩됨)
구성 파일 ( ODS_CONFIG_PATH 에서 로드됨, 기본값은 /config/ods_config.json )
환경 변수 (가장 높은 우선 순위)

구성 파일은 다음과 같은 경우에만 업데이트됩니다.

파일이 아직 존재하지 않습니다(최초 초기화)
현재 실행에 대한 환경 변수가 명시적으로 제공됩니다.

이렇게 하면 새로운 환경 변수가 설정되지 않은 경우 컨테이너가 다시 시작되어도 사용자 구성이 보존됩니다.

도구 및 별칭

도구 이름	목적	별칭
`search_web`	SearXNG를 통한 웹 검색	`search` , `web_search` , `find` , `lookup_web` , `search_online` , `access_internet` , `lookup` *
`get_website`	웹사이트 콘텐츠 스크래핑	`fetch_url` , `scrape_page` , `get` , `load_website` , `lookup` *
`get_current_datetime`	현재 날짜/시간	`current_time` , `get_time` , `current_date`

* lookup 는 상황에 따라 달라집니다.

url 인수로 호출하면 get_website 에 매핑됩니다.
그렇지 않으면 search_web 에 매핑됩니다.

예: 도구 호출

웹 검색

{ "name": "search_web", "arguments": { "query": "open source ai" } }

또는 별칭을 사용합니다.

{ "name": "search", "arguments": { "query": "open source ai" } }

카테고리별 검색

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

웹사이트 스크래핑

{ "name": "get_website", "arguments": { "url": "example.com" } }

또는 별칭을 사용합니다.

{ "name": "lookup", "arguments": { "url": "example.com" } }

현재 날짜/시간

{ "name": "get_current_datetime", "arguments": {} }

또는:

{ "name": "current_time", "arguments": {} }

고급 기능

카테고리별 검색

search_web 도구는 맞춤형 출력을 제공하는 다양한 카테고리를 지원합니다.

이미지 : 마크다운 임베딩을 선택적으로 사용하여 이미지 URL, 제목 및 소스 페이지를 반환합니다.
비디오 : 제목, 소스, 내장 URL을 포함한 비디오 정보를 반환합니다.
파일 : 형식 및 크기를 포함한 다운로드 가능한 파일 정보를 반환합니다.
map : 좌표와 주소를 포함한 위치 데이터를 반환합니다.
소셜 미디어 : 소셜 플랫폼의 게시물과 프로필을 반환합니다.
일반 : 전체 웹페이지 콘텐츠를 스크래핑하여 반환하는 기본 카테고리

Reddit URL 변환

Reddit 콘텐츠를 스크래핑할 때 URL은 자동으로 old.reddit.com 도메인으로 변환되어 콘텐츠 추출이 더욱 용이해집니다.

속도 제한

도메인 기반 속도 제한은 특정 시간 내에 동일한 도메인에 대한 과도한 요청이 발생하는 것을 방지합니다. 이를 통해 대상 웹사이트의 과부하 및 잠재적인 IP 차단을 방지할 수 있습니다.

캐시 검증

캐시된 웹사이트 콘텐츠는 유효 기간을 기준으로 자동으로 최신성 검증을 받습니다. 오래된 콘텐츠는 자동으로 새로 고쳐지고, 유효한 캐시 콘텐츠는 빠르게 제공됩니다.

오류 처리

서버는 다음과 같은 예외 유형을 사용하여 강력한 오류 처리 시스템을 구현합니다.

MCPServerError : 모든 서버 오류에 대한 기본 예외 클래스
ConfigurationError : 구성 값이 유효하지 않을 때 발생합니다.
SearXNGConnectionError : SearXNG에 대한 연결이 실패할 때 발생합니다.
WebScrapingError : 웹 스크래핑이 실패할 때 발생합니다.
RateLimitExceededError : 도메인의 속도 제한을 초과하면 발생합니다.

오류는 정보성 메시지를 통해 클라이언트에게 적절하게 전파됩니다.

문제 해결

SearXNG에 연결할 수 없습니다 . SearXNG 인스턴스가 실행 중이고 SEARXNG_ENGINE_API_BASE_URL 환경 변수가 올바른 엔드포인트를 가리키는지 확인하세요.
속도 제한 오류 : 속도 제한 오류가 너무 많이 발생하는 경우 RATE_LIMIT_REQUESTS_PER_MINUTE 조정하세요.
느린 콘텐츠 추출 : 복잡한 페이지에서 콘텐츠 처리에 더 많은 시간을 할애하려면 TRAFILATURA_TIMEOUT 늘리세요.
Docker 네트워킹 문제 : Windows/Mac에서 Docker Desktop을 사용하는 경우, host.docker.internal 호스트 머신으로 확인되어야 합니다. Linux에서는 호스트의 IP 주소를 대신 사용해야 할 수 있습니다.

감사의 말

영감을 받은 것:

SearXNG - 개인 정보를 존중하는 메타검색 엔진
Trafilatura - 텍스트 추출을 위한 웹 스크래핑 도구
ihor-sokoliuk/mcp-searxng - SearXNG용 원본 MCP 서버
nnaoycurt ( 더 나은 웹 검색 도구 )
@bwoodruff2021 ( GetTimeDate 도구 )

MCP SearXNG Enhanced

Integrations