MCP WebSearch

무제약 실시간 웹 검색 MCP 서버 - robots.txt 제약 없이 최신 정보를 LLM에게 제공합니다.

특징

• ✅ 무제약 접근: robots.txt 제약 없이 모든 사이트 크롤링
• ✅ 실시간 검색: DuckDuckGo HTML 기반 웹 검색
• ✅ SPA 지원: JavaScript 렌더링 완벽 지원 (Puppeteer)
• ✅ 본문 추출: Mozilla Readability로 깨끗한 텍스트 추출
• ✅ 스마트 캐싱: 6시간 TTL 메모리 캐시로 성능 최적화
• ✅ 다중 LLM 호환: Claude, Gemini 등 MCP 지원 LLM에서 사용 가능

테스트 완료

npm run build
node test-manual.js

# 결과:
# web_search: ✅ 통과
# extract_url: ✅ 통과
# 🎉 모든 테스트 통과! MCP 서버가 정상 작동합니다.

설치

필수 요구사항

• Node.js 18 이상
• npm 또는 yarn

1. 프로젝트 클론 및 빌드

git clone <repository-url> mcp-websearch
cd mcp-websearch

# 의존성 설치
npm install

# TypeScript 빌드
npm run build

2. MCP 설정

Claude Desktop (macOS)

설정 파일: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "/절대/경로/mcp-websearch/dist/index.js"
      ]
    }
  }
}

Claude Desktop (Windows)

설정 파일: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "C:\\절대\\경로\\mcp-websearch\\dist\\index.js"
      ]
    }
  }
}

Claude Code

설정 파일: ~/.config/claude/config.json

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": [
        "/절대/경로/mcp-websearch/dist/index.js"
      ]
    }
  }
}

NPX 실행 (권장)

NPM에 배포 후:

{
  "mcpServers": {
    "websearch": {
      "command": "npx",
      "args": ["-y", "mcp-websearch"]
    }
  }
}

로컬 개발 시:

{
  "mcpServers": {
    "websearch": {
      "command": "npx",
      "args": [
        "-y",
        "--prefix",
        "/절대/경로/mcp-websearch",
        "mcp-websearch"
      ]
    }
  }
}

3. Claude 재시작

설정 파일 수정 후 Claude Desktop 또는 Claude Code를 재시작하세요.

사용법

web_search - 웹 검색

DuckDuckGo HTML 검색을 통해 상위 결과를 크롤링하고 본문 텍스트를 추출합니다.

파라미터:

• query (필수): 검색어
• max_results (선택): 결과 개수 (기본값: 5, 최대: 10)
• force_refresh (선택): 캐시 무시 (기본값: false)

예시:

사용자: "2026년 최신 AI 뉴스 검색해줘"
Claude: [web_search 도구 자동 호출]

응답 형식:

{
  "results": [
    {
      "title": "페이지 제목",
      "url": "https://example.com",
      "content": "추출된 본문 텍스트...",
      "snippet": "검색 결과 스니펫",
      "timestamp": "2026-02-05T00:00:00.000Z"
    }
  ],
  "query": "검색어",
  "cached": false,
  "search_time_ms": 5000
}

extract_url - URL 콘텐츠 추출

특정 URL의 웹 페이지 텍스트를 추출합니다.

파라미터:

• url (필수): 대상 URL
• use_readability (선택): Readability 사용 여부 (기본값: true)

예시:

사용자: "이 블로그 포스트 요약해줘: https://example.com/article"
Claude: [extract_url 도구 자동 호출]

응답 형식:

{
  "title": "페이지 제목",
  "url": "https://example.com/article",
  "content": "추출된 텍스트...",
  "length": 5000,
  "timestamp": "2026-02-05T00:00:00.000Z"
}

기술 스택

• Node.js - 런타임 환경
• TypeScript - 타입 안전성
• @modelcontextprotocol/sdk - MCP 서버 프레임워크
• Puppeteer - 헤드리스 브라우저 (SPA 지원)
• @mozilla/readability - 본문 추출 알고리즘
• jsdom - HTML 파싱
• node-cache - 메모리 캐싱

캐싱

동일한 검색어는 6시간 동안 캐시됩니다. 캐시를 무시하려면 force_refresh: true를 사용하세요.

캐시 확인:

캐시 히트: cached: true, 응답 시간 ~100ms
캐시 미스: cached: false, 응답 시간 ~5초

트러블슈팅

MCP 서버 연결 실패

# 빌드 확인
npm run build

# dist/index.js 존재 확인
ls -la dist/index.js

# 직접 실행 테스트
node dist/index.js

Puppeteer 에러

# Chromium 재설치
npm install puppeteer --force

검색 결과 없음

• Google CAPTCHA 발생 가능성 (과도한 요청)
• 잠시 기다린 후 재시도
• force_refresh: false로 캐시 사용 권장

제약사항

• 개인 용도: robots.txt를 무시하므로 개인 용도로만 사용 권장
• Google CAPTCHA: 과도한 요청 시 CAPTCHA 발생 가능
• 메모리 사용: Puppeteer는 메모리를 많이 사용 (병렬 5개 제한)
• 속도: 실시간 크롤링이므로 API보다 느림 (캐싱으로 완화)

개발

# 개발 모드 (TypeScript watch)
npm run dev

# 빌드
npm run build

# 로컬 실행
npm start

# 디버그 모드
DEBUG=true node dist/index.js

라이선스

MIT

기여

이슈와 PR은 환영합니다!

참고 자료

• MCP 공식 문서
• Puppeteer 문서
• Readability 저장소