Skip to main content
Glama

web-search-mcp

로컬 LLM을 위한 외부 웹 검색 및 페이지 가져오기 기능으로, MCP 도구 및 CLI로 노출됩니다. 구현은 Playwright 우선, 비동기 방식이며 기본적으로 시스템에 설치된 Chromium 바이너리를 실행합니다. 설계 이력은 docs/IMPLEMENTATION_PLAN.md에 문서화되어 있습니다.

도구

  • search(provider, context)는 duckduckgo(기본값), google 또는 yandex에서 브라우저 기반 검색을 실행하고 최대 5개의 유기적 결과 URL을 반환합니다.

  • fetch(urls)는 1..5개의 URL을 가져와 URL별 pages, errors, truncated 필드가 포함된 브라우저 렌더링 HTML을 반환합니다.

context는 호출자 호환성을 위해 의도적으로 검색 쿼리 문자열로 설정되었습니다.

Related MCP server: Web Search MCP

설정

uv sync
chromium --version

Chromium이 표준이 아닌 위치에 설치된 경우 PLAYWRIGHT_CHROMIUM_EXECUTABLE=/path/to/chromium을 설정하세요.

사용법

stdio를 통해 MCP 서버 실행:

uv run web-search serve-mcp

CLI 직접 실행:

uv run web-search search --context "python async playwright"
uv run web-search fetch https://example.com

stdio 대신 HTTP 전송 노출:

uv run web-search serve-mcp --transport streamable-http --host 127.0.0.1 --port 8000

설계 참고 사항

  • 프로세스당 하나의 공유 브라우저를 사용하며, 요청마다 새로운 시크릿 컨텍스트를 사용합니다.

  • Playwright는 Playwright가 다운로드한 브라우저 번들이 아닌 시스템 Chromium 바이너리를 실행합니다.

  • 시스템 Chromium은 Playwright와 잘 작동하지만, 테스트된 시스템 Firefox 빌드는 실행 직후 종료되었습니다. 따라서 이 저장소는 지원되는 호스트 브라우저 경로로 시스템 Chromium을 대상으로 합니다.

  • 브라우저 스모크 테스트는 일반 호스트 셸에서 실행해야 합니다. 제한된 샌드박스는 호스트 브라우저가 올바르게 작동하더라도 Chromium 시작을 차단할 수 있습니다.

  • 전역 탐색 동시성 제한은 3입니다.

  • 시간 제한: 페이지당 15s, search 총 20s, fetch 총 35s.

  • SSRF 방지: http/https만 허용, 포함된 자격 증명 없음, 탐색 전 및 브라우저 하위 요청 시 루프백/사설/링크 로컬/예약된 IP 차단.

  • JavaScript 챌린지 페이지에는 10s의 제한된 대기 시간이 주어지며, CAPTCHA 해결, 스텔스 핑거프린팅 또는 사이트별 우회 로직은 없습니다.

  • HTML은 URL당 1 MiB로 제한되며, 크기가 초과된 응답은 잘리고 truncated 필드에 보고됩니다.

  • v1에서는 robots.txt를 참조하지 않습니다.

개발

source .venv/bin/activate
pytest

파서 테스트는 저장된 HTML 픽스처에 대해 실행되며, 선택자 드리프트는 예상되는 유지 관리 비용입니다.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables web searching through Google, DuckDuckGo, and Bing using a headless Chrome browser, returning structured results with titles, URLs, and snippets. Also supports fetching and extracting text content from any webpage.
      16
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides web access capabilities for LLMs including search, fetching, content extraction, PDF reading, image viewing, and screenshots.
      3
      33 PyPI
      46
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to perform web searches, extract webpage content, and conduct end-to-end search-and-extract operations using multiple search providers and content extraction methods.
      -