MCP Web Search Pro

확장된 자체 호스팅 웹 리서치 서버로, MCP 호환 클라이언트를 위한 도구입니다. AI 어시스턴트에게 웹 페이지 탐색, 읽기 가능한 콘텐츠 추출, JavaScript 애플리케이션 렌더링, 페이지를 사용할 수 없을 때 Internet Archive 활용, YouTube 자막 읽기를 위한 도구를 제공합니다.

이 서비스는 로컬 또는 신뢰할 수 있는 네트워크 환경에서 사용하도록 설계되었습니다. 상태 비저장(stateless) 방식이며, API 키가 필요 없고, 포트 8082에서 MCP Streamable HTTP 전송 방식을 노출합니다. 다른 포트에서 더 가벼운 웹 검색 MCP 서버와 함께 실행할 수 있습니다.

포트 8082의 별도 컨테이너로 실행되며, 가벼운 mcp-web-search(포트 8081)와 함께 사용됩니다. 작업에 맞는 클라이언트를 선택하여 사용하세요. Pro 버전이 느리게 느껴지더라도 가벼운 버전은 그대로 사용할 수 있습니다.

기능

• DuckDuckGo를 통한 웹 검색, 결과 제한 및 지역 선택 기능.

• 탐색 및 보일러플레이트를 제거한 읽기 가능한 HTML을 Markdown으로 추출.

• 자동 PDF 감지 및 텍스트 추출.

• React, Vue, SPA 및 기타 JS 중심 페이지를 위한 헤드리스 Chromium 렌더링.

• 사용 불가능하거나 변경된 페이지를 위한 Wayback Machine 스냅샷.

• URL 또는 비디오 ID에서 YouTube 트랜스크립트 제공, 선택적 타임스탬프 포함.

• 컨테이너 및 프로세스 확인을 위한 /health 엔드포인트.

• 상태 비저장 Streamable HTTP 및 stdio MCP 전송 방식.

Related MCP server: Basic MCP Tools

MCP 도구

일반 페이지에는 더 빠른 web_fetch를 사용하세요. 사이트가 클라이언트 측 JavaScript에 의존하여 첫 번째 도구가 빈 껍데기나 불완전한 콘텐츠를 반환하는 경우에만 web_fetch_js를 사용하세요.

Docker로 실행

docker compose up -d --build

확인:

curl http://localhost:8082/health      # → {"status":"ok"}

로그 / 재시작 / 중지:

docker compose logs -f
docker compose restart
docker compose down

첫 번째 빌드는 Chromium을 다운로드하므로 크기가 큽니다(~400MB). 이후 빌드는 캐시된 레이어를 재사용합니다.

클라이언트 연결

MCP 호환 클라이언트를 다음 주소로 연결하세요:

http://<server-host>:8082/mcp

헤더나 API 키가 필요하지 않습니다. 서버는 상태 비저장 모드로 실행됩니다.

Docker 없이 로컬에서 실행

Python 3.12를 권장합니다:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
playwright install --with-deps chromium
python server.py

HTTP 전송 방식을 직접 실행하려면:

python server.py --sse --host 127.0.0.1 --port 8082

역사적인 --sse 옵션 이름에도 불구하고, HTTP 구현은 상태 비저장 MCP Streamable HTTP 전송 방식을 사용합니다.

성능 참고 사항

• 런타임에 무거운 것은 web_fetch_js뿐입니다. 호출당 Chromium을 실행합니다(~5–15초). 나머지 네 가지 도구는 가벼운 순수 Python으로 빠르게 작동합니다.

• docker-compose.yml의 shm_size: 1gb는 컨테이너 내 Chromium 샌드박스 충돌을 방지합니다.

• 일반적인 비JS 페이지에는 web_fetch(빠름)를 사용하고, JavaScript로 콘텐츠를 렌더링하는 React/Vue/SPA 사이트에는 web_fetch_js를 사용하세요.

설정

포트를 변경하려면 docker-compose.yml에서 ports: 매핑과 command:를 모두 편집하세요. 디버깅을 위해 원시 요청/응답 로깅을 활성화하려면 주석 처리된 --verbose command: 줄로 전환하세요.

검증

이 저장소는 소스 코드 및 Docker 빌드 구성으로 푸시되도록 설계되었습니다. 현재 자동화된 테스트 스위트는 없습니다. 권장되는 프로젝트 확인 사항은 다음과 같습니다:

git diff --check
docker compose config
docker compose up -d --build
curl http://localhost:8082/health
docker compose logs --tail=100
docker compose down

인증을 추가하거나 신뢰할 수 있는 리버스 프록시 뒤에 배치하지 않고 이 서비스를 공개 인터넷에 직접 게시하지 마십시오. HTTP 모드는 0.0.0.0에 바인딩되고, API 키 없이 요청을 허용하며, 모든 출처를 허용합니다. 이는 로컬 MCP 클라이언트에 편리하지만 접근 제어 계층이 아닙니다.

보안 및 운영 참고 사항

• web_fetch 및 web_fetch_js는 임의의 HTTP(S) URL을 요청할 수 있습니다. 신뢰할 수 없는 사용자가 서비스를 호출할 수 있는 경우 네트워크 액세스를 제한하거나 URL/DNS 보호 장치를 추가하세요.

• --verbose는 요청 및 응답 본문을 기록하므로 짧은 로컬 디버깅 세션 외에는 비활성화된 상태로 유지하세요.

• 종속성은 최소 버전 제약 조건을 사용합니다. 재현 가능한 프로덕션 빌드에 의존하기 전에 버전을 고정(pin)하거나 잠금(lock)하세요.

파일

• server.py — MCP 서버(5개 도구)

• requirements.txt — mcp, httpx, beautifulsoup4, markdownify, ddgs, trafilatura, pypdf, youtube-transcript-api, playwright

• Dockerfile — Python 3.12-slim + Playwright Chromium

• docker-compose.yml — shm_size: 1gb로 포트 8082에서 서비스 실행

라이선스

현재 라이선스 파일이 포함되어 있지 않습니다. 외부 기여를 받거나 프로젝트를 재배포하기 전에 라이선스를 추가하세요.