webscout-mcp

AI 에이전트를 위한 웹 검색 및 가져오기 도구로, MCP 서버로 동작합니다. 검색, 가져오기, 크롤링, 구조화된 데이터 추출을 지원합니다 - API 키가 필요 없고, 요청별 과금이 없으며, 모든 것이 사용자 머신에서 처리됩니다.

설치

pip install webscout-mcp

Python 3.10+ 필요.

Related MCP server: Crawl4AI RAG MCP Server

빠른 시작

MCP 클라이언트 설정(Claude Code, Cursor, Codex 등)에 추가하세요:

{
  "mcpServers": {
    "webscout": {
      "command": "webscout-mcp",
      "args": []
    }
  }
}

끝입니다. 에이전트에 6가지 도구가 제공됩니다:

• web_search - 키 없이 Bing 검색, 자동 DuckDuckGo HTML 폴백 지원

• web_fetch - 페이지를 가져와 본문 기사 추출 (markdown/text/html)

• web_crawl - 깊이/페이지 제한이 있는 동시 BFS 크롤링, robots.txt 준수

• web_extract - CSS 선택자, 속성, 정규식으로 구조화된 데이터 추출

• cache_stats - 로컬 캐시 검사

• cache_clear - 캐시 비우기

CLI 사용법

MCP 서버로 실행하는 것 외에도, webscout-mcp를 명령줄에서 직접 사용할 수 있습니다:

# Search the web (outputs JSON)
webscout-mcp search "python async libraries" --max-results 5

# Fetch a page (raw content)
webscout-mcp fetch https://example.com --extract --format markdown --raw

# Crawl a site
webscout-mcp crawl https://example.com --depth 2 --pages 10

# Start MCP server (default if no command given)
webscout-mcp serve --transport stdio

사용 예시

검색

web_search(query="best python async libraries", max_results=5)

제목, URL, 스니펫, 그리고 요청을 처리한 백엔드(bing 또는 duckduckgo)가 포함된 구조화된 결과를 반환합니다. Bing이 실패하거나 마크업이 변경되면 엔진이 자동으로 DuckDuckGo의 HTML 버전으로 폴백합니다 - 설정이 필요 없습니다.

페이지 가져오기

web_fetch(url="https://example.com", extract=true, output_format="markdown")

extract=true는 trafilatura(readability-lxml 폴백 포함)를 실행하여 내비게이션, 광고, 사이드바를 제거합니다 - 원시 HTML이 아닌 깔끔한 기사 콘텐츠를 얻을 수 있습니다.

구조화된 데이터 추출

web_extract(
  url="https://example.com/products",
  rules='[
    {"name": "titles", "selector": ".product h2", "multiple": true},
    {"name": "prices", "selector": ".price", "regex": "\\$([\\d.]+)", "multiple": true},
    {"name": "links", "selector": "a.product", "attribute": "href", "multiple": true}
  ]'
)

각 규칙은 selector, attribute, multiple, regex, default를 지원합니다.

사이트 크롤링

web_crawl(seed_url="https://example.com", max_depth=2, max_pages=10, concurrency=5)

각 깊이 수준의 페이지는 동시에 가져옵니다(concurrency로 제어, 기본값 5). 크롤러는 기본적으로 robots.txt를 준수합니다 - 허용되지 않은 URL은 건너뛰고 skipped_robots에 집계됩니다. 동일 도메인 제한이 기본적으로 활성화되어 있습니다.

Python 라이브러리로 사용

import asyncio
from webscout_mcp import Config, Fetcher, SearchEngine

async def main():
    config = Config.from_env()
    config.ensure_dirs()

    fetcher = Fetcher(config)
    result = await fetcher.fetch("https://example.com", extract=True)
    print(result.title)
    print(result.content[:500])
    await fetcher.close()

    search = SearchEngine(config)
    results = await search.search("python async", max_results=5)
    for r in results:
        print(f"{r.position}. {r.title} - {r.url} ({r.backend})")
    await search.close()

asyncio.run(main())

작동 방식

• 검색은 먼저 Bing을 시도한 다음 DuckDuckGo HTML을 시도합니다 - 둘 다 직접 HTTP 스크래핑 방식이며 API 키가 필요 없습니다. 결과는 쿼리별로 캐시됩니다.

• 가져오기는 지수 백오프 재시도(모든 httpx 오류 + HTTP 5xx), 도메인별 토큰 버킷 속도 제한, 5MB 콘텐츠 상한이 있는 httpx를 사용합니다.

• 콘텐츠 추출은 trafilatura를 기본으로, readability-lxml을 자동 폴백으로 사용합니다 - 많은 읽기-나중에 서비스에서 사용하는 것과 동일한 라이브러리입니다.

• 캐싱은 TTL과 크기 상한이 있는 SQLite를 사용하며, 오래된 항목은 자동으로 제거됩니다. 반복 가져오기와 검색은 비용이 들지 않습니다.

• 크롤링은 구성 가능한 깊이, 페이지 수, 동시성, 동일 도메인 제한, robots.txt 준수를 갖춘 동시 BFS입니다. 각 페이지의 이중 가져오기를 피하기 위해 초기 가져오기의 원시 HTML을 사용합니다.

• 프록시 지원 - 구성 또는 환경 변수를 통해 모든 HTTP/HTTPS 요청을 프록시로 라우팅합니다.

• 로깅은 구조화되어 있으며 WEBSCOUT_LOG_LEVEL(DEBUG/INFO/WARNING/ERROR) 및 JSON 출력용 WEBSCOUT_LOG_JSON=1을 통해 구성할 수 있습니다.

모든 것이 로컬에서 실행됩니다. 데이터가 사용자 머신을 벗어나지 않습니다.

구성

모든 설정에는 합리적인 기본값이 있습니다. 환경 변수(WEBSCOUT_ 접두사), TOML 구성 파일, 또는 CLI 플래그로 재정의할 수 있습니다.

구성 파일

~/.config/webscout/config.toml(또는 $XDG_CONFIG_HOME/webscout/config.toml)을 생성하세요:

[cache]
ttl = 7200
max_size_mb = 512

[fetch]
timeout = 15.0
max_retries = 3

[proxy]
http = "http://proxy:8080"
https = "http://proxy:8080"

[search]
max_results = 10
backends = ["bing", "duckduckgo"]

[crawler]
max_depth = 2
max_pages = 20
concurrency = 5
respect_robots = true

[logging]
level = "WARNING"
json = false

환경 변수가 구성 파일 값을 재정의합니다.

환경 변수

CLI 플래그가 환경 변수를 재정의합니다:

webscout-mcp --cache-ttl 3600 --cache-dir /tmp/webscout serve

전송 방식

# stdio (default - works with Claude Code, Cursor, etc.)
webscout-mcp

# SSE (for remote or browser-based clients)
webscout-mcp serve --transport sse --host 0.0.0.0 --port 8000

변경 로그

0.3.0

• TOML 구성 파일 지원: 환경 변수 외에도 ~/.config/webscout/config.toml로 구성 가능

• HTTP/HTTPS 프록시 지원: 모든 요청을 프록시로 라우팅

• 이중 콘텐츠 추출: trafilatura 기본, readability-lxml 자동 폴백

• 검색 결과 중복 제거: 중복 URL 제거, 위치 재번호 지정

• 지역 인식 검색: region 매개변수가 이제 실제로 Bing과 DuckDuckGo에 전달됨

• 크롤러 성능: 페이지당 이중 가져오기 제거 - 크롤링 속도 약 2배 향상

• 더 나은 재시도 로직: 모든 httpx 오류 및 HTTP 5xx에서 재시도

• 콘텐츠 유형 감지 수정: 올바른 HTML/XML 감지

0.2.0

• 다중 백엔드 검색: 자동 장애 조치가 있는 Bing + DuckDuckGo HTML

• 구성 가능한 병렬 처리를 갖춘 동시 크롤러

• robots.txt 준수(구성 가능, 기본 활성화)

• CLI 하위 명령: search, fetch, crawl, serve

• 콘솔 및 JSON 포맷터를 갖춘 구조화된 로깅

• 더 나은 오류 처리를 위한 사용자 정의 예외 계층

• 새 구성: WEBSCOUT_SEARCH_BACKENDS, WEBSCOUT_CRAWLER_CONCURRENCY, WEBSCOUT_RESPECT_ROBOTS

0.1.0

• 초기 릴리스: web_search, web_fetch, web_crawl, web_extract, cache_stats, cache_clear

• TTL 및 크기 기반 제거가 있는 SQLite 캐시

• 도메인별 토큰 버킷 속도 제한

• 지수 백오프 재시도

• trafilatura 콘텐츠 추출

개발

git clone https://github.com/wxs-lang/webscout-mcp.git
cd webscout-mcp
pip install -e ".[dev]"
pytest

라이선스

MIT