웹 검색-MCP

대장간 배지

stdio 전송을 통해 웹 검색 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. 이 서버는 WebSearch 크롤러 API와 통합되어 검색 결과를 가져옵니다.

에 대한

WebSearch-MCP는 MCP를 지원하는 AI 비서에 웹 검색 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. Claude와 같은 AI 모델이 실시간으로 웹을 검색하여 모든 주제에 대한 최신 정보를 검색할 수 있도록 지원합니다.

서버는 실제 웹 검색을 처리하는 크롤러 API 서비스와 통합되고, 표준화된 모델 컨텍스트 프로토콜을 사용하여 AI 도우미와 통신합니다.

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 WebSearch를 자동으로 설치하려면:

지엑스피1

수동 설치

npm install -g websearch-mcp

또는 설치하지 않고 사용하세요:

npx websearch-mcp

구성

WebSearch MCP 서버는 환경 변수를 사용하여 구성할 수 있습니다.

API_URL : WebSearch 크롤러 API의 URL(기본값: http://localhost:3001 )
MAX_SEARCH_RESULT : 요청에 지정되지 않은 경우 반환할 검색 결과의 최대 수(기본값: 5 )

예:

# Configure API URL API_URL=https://crawler.example.com npx websearch-mcp # Configure maximum search results MAX_SEARCH_RESULT=10 npx websearch-mcp # Configure both API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

설정 및 통합

WebSearch-MCP를 설정하는 데는 두 가지 주요 부분이 포함됩니다. 실제 웹 검색을 수행하는 크롤러 서비스를 구성하는 것과 MCP 서버를 AI 클라이언트 애플리케이션과 통합하는 것입니다.

크롤러 서비스 설정

WebSearch MCP 서버는 실제 웹 검색을 수행하기 위해 크롤러 서비스가 필요합니다. Docker Compose를 사용하여 크롤러 서비스를 쉽게 설정할 수 있습니다.

필수 조건

Docker 와 Docker Compose

크롤러 서비스 시작

다음 내용으로 docker-compose.yml 이라는 파일을 만듭니다.

version: '3.8' services: crawler: image: laituanmanh/websearch-crawler:latest container_name: websearch-api restart: unless-stopped ports: - "3001:3001" environment: - NODE_ENV=production - PORT=3001 - LOG_LEVEL=info - FLARESOLVERR_URL=http://flaresolverr:8191/v1 depends_on: - flaresolverr volumes: - crawler_storage:/app/storage flaresolverr: image: 21hsmw/flaresolverr:nodriver container_name: flaresolverr restart: unless-stopped environment: - LOG_LEVEL=info - TZ=UTC volumes: crawler_storage:

Mac Apple Silicon에 대한 해결 방법

version: '3.8' services: crawler: image: laituanmanh/websearch-crawler:latest container_name: websearch-api platform: "linux/amd64" restart: unless-stopped ports: - "3001:3001" environment: - NODE_ENV=production - PORT=3001 - LOG_LEVEL=info - FLARESOLVERR_URL=http://flaresolverr:8191/v1 depends_on: - flaresolverr volumes: - crawler_storage:/app/storage flaresolverr: image: 21hsmw/flaresolverr:nodriver platform: "linux/arm64" container_name: flaresolverr restart: unless-stopped environment: - LOG_LEVEL=info - TZ=UTC volumes: crawler_storage:

서비스 시작:

docker-compose up -d

서비스가 실행 중인지 확인하세요.

docker-compose ps

크롤러 API 상태 엔드포인트를 테스트합니다.

curl http://localhost:3001/health

예상 응답:

{ "status": "ok", "details": { "status": "ok", "flaresolverr": true, "google": true, "message": null } }

크롤러 API는 http://localhost:3001 에서 사용할 수 있습니다.

크롤러 API 테스트

curl을 사용하여 크롤러 API를 직접 테스트할 수 있습니다.

curl -X POST http://localhost:3001/crawl \ -H "Content-Type: application/json" \ -d '{ "query": "typescript best practices", "numResults": 2, "language": "en", "filters": { "excludeDomains": ["youtube.com"], "resultType": "all" } }'

사용자 정의 구성

docker-compose.yml 파일에서 환경 변수를 수정하여 크롤러 서비스를 사용자 정의할 수 있습니다.

PORT : 크롤러 API가 수신하는 포트(기본값: 3001)
LOG_LEVEL : 로깅 레벨(옵션: debug, info, warn, error)
FLARESOLVERR_URL : FlareSolverr 서비스의 URL(Cloudflare 보호를 우회하기 위한)

MCP 클라이언트와 통합

빠른 참조: MCP 구성

다음은 다양한 클라이언트에서 MCP를 구성하는 방법에 대한 간단한 참조입니다.

{ "mcpServers": { "websearch": { "command": "npx", "args": [ "websearch-mcp" ], "environment": { "API_URL": "http://localhost:3001", "MAX_SEARCH_RESULT": "5" // reduce to save your tokens, increase for wider information gain } } } }

Windows의 해결 방법( 문제 로 인해)

{ "mcpServers": { "websearch": { "command": "cmd", "args": [ "/c", "npx", "websearch-mcp" ], "environment": { "API_URL": "http://localhost:3001", "MAX_SEARCH_RESULT": "1" } } } }

용법

이 패키지는 다음 매개변수를 사용하여 web_search 도구를 노출하는 stdio 전송을 사용하는 MCP 서버를 구현합니다.

매개변수

query (필수): 검색할 검색어
numResults (선택 사항): 반환할 결과 수(기본값: 5)
language (선택 사항): 검색 결과에 대한 언어 코드(예: 'en')
region (선택 사항): 검색 결과에 대한 지역 코드(예: 'us')
excludeDomains (선택 사항): 결과에서 제외할 도메인
includeDomains (선택 사항): 결과에 이 도메인만 포함합니다.
excludeTerms (선택 사항): 결과에서 제외할 용어
resultType (선택 사항): 반환할 결과 유형('모두', '뉴스' 또는 '블로그')

검색 응답 예시

다음은 검색 응답의 예입니다.

{ "query": "machine learning trends", "results": [ { "title": "Top Machine Learning Trends in 2025", "snippet": "The key machine learning trends for 2025 include multimodal AI, generative models, and quantum machine learning applications in enterprise...", "url": "https://example.com/machine-learning-trends-2025", "siteName": "AI Research Today", "byline": "Dr. Jane Smith" }, { "title": "The Evolution of Machine Learning: 2020-2025", "snippet": "Over the past five years, machine learning has evolved from primarily supervised learning approaches to more sophisticated self-supervised and reinforcement learning paradigms...", "url": "https://example.com/ml-evolution", "siteName": "Tech Insights", "byline": "John Doe" } ] }

로컬 테스트

WebSearch MCP 서버를 로컬로 테스트하려면 포함된 테스트 클라이언트를 사용할 수 있습니다.

npm run test-client

이렇게 하면 MCP 서버가 시작되고, 검색어를 입력하고 결과를 볼 수 있는 간단한 명령줄 인터페이스가 시작됩니다.

테스트 클라이언트에 대한 API_URL을 구성할 수도 있습니다.

API_URL=https://crawler.example.com npm run test-client

도서관으로서

이 패키지를 프로그래밍 방식으로 사용할 수 있습니다.

import { createMCPClient } from '@modelcontextprotocol/sdk'; // Create an MCP client const client = createMCPClient({ transport: { type: 'subprocess', command: 'npx websearch-mcp' } }); // Execute a web search const response = await client.request({ method: 'call_tool', params: { name: 'web_search', arguments: { query: 'your search query', numResults: 5, language: 'en' } } }); console.log(response.result);

문제 해결

크롤러 서비스 문제

API에 접근할 수 없음 : 크롤러 서비스가 실행 중이고 구성된 API_URL에서 접근 가능한지 확인하세요.
검색 결과가 없습니다 . 크롤러 서비스 로그를 확인하여 오류가 있는지 확인하세요.
docker-compose logs crawler
FlareSolverr 문제 : 일부 웹사이트는 Cloudflare 보호 기능을 사용합니다. 이와 관련된 오류가 발생하면 FlareSolverr가 작동하는지 확인하세요.
docker-compose logs flaresolverr

MCP 서버 문제

가져오기 오류 : MCP SDK의 최신 버전을 사용하고 있는지 확인하세요.
npm install -g @modelcontextprotocol/sdk@latest
연결 문제 : 클라이언트에 대해 stdio 전송이 올바르게 구성되었는지 확인하세요.

개발

이 프로젝트를 진행하려면:

저장소를 복제합니다
종속성 설치: npm install
프로젝트 빌드: npm run build
개발 모드에서 실행: npm run dev

서버는 포함된 swagger.json 파일에 정의된 WebSearch 크롤러 API를 기대합니다. API가 구성된 API_URL에서 실행 중인지 확인하세요.

프로젝트 구조

.gitignore : Git이 무시해야 하는 파일(node_modules, dist, log 등)을 지정합니다.
.npmignore : npm에 게시할 때 포함되지 않아야 하는 파일을 지정합니다.
package.json : 프로젝트 메타데이터 및 종속성
src/ : 소스 TypeScript 파일
dist/ : 컴파일된 JavaScript 파일(빌드 시 생성됨)

npm에 게시하기

이 패키지를 npm에 게시하려면:

npm 계정이 있고 로그인되어 있는지 확인하세요( npm login )
package.json에서 버전을 업데이트합니다( npm version patch|minor|major )
npm publish 실행하세요

.npmignore 파일은 게시된 패키지에 필요한 파일만 포함되도록 보장합니다.

dist/ 에 컴파일된 코드
README.md 및 LICENSE 파일
패키지.json

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

아이에스씨

WebSearch-MCP