웹 검색-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