🚀 OneSearch MCP 서버: 웹 검색 & 크롤 & 스크래퍼 & 콘텐츠 준비

웹 검색, 로컬 브라우저 검색, 그리고 agent-browser를 활용한 스크래핑 기능을 위해 여러 검색 제공업체와 통합되는 Model Context Protocol (MCP) 서버 구현체입니다.

주요 기능

• 웹 검색, 스크래핑, 크롤링 및 웹사이트 콘텐츠 전처리.

• 다양한 검색 엔진 및 웹 스크래퍼 지원: SearXNG, Tavily, DuckDuckGo, Bing, Google, Zhipu (智谱), Exa, Bocha (博查) 등.

• 로컬 웹 검색 (브라우저 검색), 다양한 검색 엔진 지원: Bing, Google, Baidu, Sogou 등.

  • 브라우저 자동화를 위해 agent-browser 사용.

  • 무료, API 키 불필요.

• 활성화된 도구: one_search, one_scrape, one_map, one_extract

Related MCP server: MCP Web Tools Server

v1.1.0 및 이전 버전에서의 마이그레이션

v1.1.0의 주요 변경 사항:

• Firecrawl 제거: 외부 API 서비스 없이 유사한 기능을 제공하는 agent-browser를 사용하기 위해 Firecrawl 통합이 제거되었습니다.

• 새로운 브라우저 요구 사항: Chromium 브라우저를 설치해야 합니다 (필수 구성 요소 섹션 참조).

• 환경 변수: FIRECRAWL_API_URL 및 FIRECRAWL_API_KEY는 더 이상 사용되지 않습니다.

변경 사항:

• one_scrape 및 one_map은 이제 Firecrawl 대신 agent-browser를 사용합니다.

• one_extract는 이제 내장 LLM 추출을 수행하는 대신 다운스트림 분석을 위해 다중 URL 페이지 콘텐츠를 전처리합니다.

• 모든 브라우저 기반 작업은 이제 로컬에서 처리되어 개인 정보 보호가 강화되고 API 비용이 발생하지 않습니다.

마이그레이션 단계:

1. Chromium 브라우저 설치 (필수 구성 요소 참조)

2. 환경 변수에서 FIRECRAWL_API_URL 및 FIRECRAWL_API_KEY 제거

3. 최신 버전으로 업데이트: npm install -g one-search-mcp@latest

필수 구성 요소

브라우저 요구 사항: 이 서버는 웹 스크래핑 및 로컬 검색을 위해 agent-browser를 사용하며, Chromium 기반 브라우저가 필요합니다.

좋은 소식: 서버가 시스템에 이미 설치된 브라우저를 자동으로 감지하여 사용합니다:

• ✅ Google Chrome

• ✅ Microsoft Edge

• ✅ Chromium

• ✅ Google Chrome Canary

이러한 브라우저가 설치되어 있지 않은 경우, 다음을 수행할 수 있습니다:

# Option 1: Install Google Chrome (Recommended)
# Download from: https://www.google.com/chrome/

# Option 2: Install Microsoft Edge
# Download from: https://www.microsoft.com/edge

# Option 3: Install Chromium via agent-browser
npx agent-browser install

# Option 4: Install Chromium directly
# Download from: https://www.chromium.org/getting-involved/download-chromium/

설치

Claude Code CLI 사용 (권장)

# Add to Claude Code with default settings (local search)
claude mcp add one-search-mcp -- npx -y one-search-mcp

# Add with custom search provider (e.g., SearXNG)
claude mcp add one-search-mcp -e SEARCH_PROVIDER=searxng -e SEARCH_API_URL=http://127.0.0.1:8080 -- npx -y one-search-mcp

# Add with Tavily API
claude mcp add one-search-mcp -e SEARCH_PROVIDER=tavily -e SEARCH_API_KEY=your_api_key -- npx -y one-search-mcp

수동 설치

# Install globally (Optional)
npm install -g one-search-mcp

# Or run directly with npx
npx -y one-search-mcp

Docker 사용

Docker 이미지에는 모든 종속성(Chromium 브라우저)이 미리 설치되어 있어 추가 설정이 필요하지 않습니다.

이미지 가져오기:

# From GitHub Container Registry
docker pull ghcr.io/yokingma/one-search-mcp:latest

# Or from Docker Hub
docker pull zacma/one-search-mcp:latest

Claude Desktop 설정:

{
 "mcpServers": {
 "one-search-mcp": {
 "command": "docker",
 "args": ["run", "-i", "--rm", "ghcr.io/yokingma/one-search-mcp:latest"],
 "env": {
 "SEARCH_PROVIDER": "local"
 }
 }
 }
}

사용자 지정 검색 제공업체 사용 시:

{
 "mcpServers": {
 "one-search-mcp": {
 "command": "docker",
 "args": [
 "run", "-i", "--rm",
 "-e", "SEARCH_PROVIDER=tavily",
 "-e", "SEARCH_API_KEY=your_api_key",
 "ghcr.io/yokingma/one-search-mcp:latest"
 ]
 }
 }
}

환경 변수

검색 엔진:

• SEARCH_PROVIDER (선택 사항): 사용할 검색 제공업체. searxng, duckduckgo, bing, tavily, google, zhipu, exa, bocha, local을 지원하며 기본값은 local입니다.

• SEARCH_API_URL (선택 사항): SearxNG API의 URL 또는 google을 위한 Google 맞춤 검색 엔진 ID.

• SEARCH_API_KEY (선택 사항): 검색 제공업체용 API 키. tavily, bing, google, zhipu, exa, bocha에 필요합니다.

// supported search providers
export type SearchProvider = 'searxng' | 'duckduckgo' | 'bing' | 'tavily' | 'google' | 'zhipu' | 'exa' | 'bocha' | 'local';

검색 제공업체 구성

다른 MCP 클라이언트를 위한 구성

Claude Desktop

Claude Desktop 구성 파일에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
 "mcpServers": {
 "one-search-mcp": {
 "command": "npx",
 "args": ["-y", "one-search-mcp"],
 "env": {
 "SEARCH_PROVIDER": "local"
 }
 }
 }
}

Cursor

mcp.json 파일에 추가하세요:

{
 "mcpServers": {
 "one-search-mcp": {
 "command": "npx",
 "args": ["-y", "one-search-mcp"],
 "env": {
 "SEARCH_PROVIDER": "local"
 }
 }
 }
}

Windsurf

./codeium/windsurf/model_config.json 파일에 추가하세요:

{
 "mcpServers": {
 "one-search-mcp": {
 "command": "npx",
 "args": ["-y", "one-search-mcp"],
 "env": {
 "SEARCH_PROVIDER": "local"
 }
 }
 }
}

SearXNG 자체 호스팅 (선택 사항)

SearXNG를 검색 제공업체로 사용하려면 Docker를 사용하여 로컬에 배포할 수 있습니다:

필수 구성 요소:

• Docker 설치 및 실행 중 (버전 20.10.0 이상)

• 최소 4GB RAM 사용 가능

빠른 시작:

# Clone SearXNG Docker repository
git clone https://github.com/searxng/searxng-docker.git
cd searxng-docker

# Start SearXNG
docker compose up -d

배포 후 SearXNG는 기본적으로 http://127.0.0.1:8080에서 사용할 수 있습니다.

OneSearch가 SearXNG를 사용하도록 구성:

# Set environment variables
export SEARCH_PROVIDER=searxng
export SEARCH_API_URL=http://127.0.0.1:8080

자세한 내용은 공식 SearXNG Docker 문서를 참조하세요.

문제 해결

브라우저를 찾을 수 없음 오류

"Browser not found"와 같은 오류가 표시되면 서버가 설치된 Chromium 기반 브라우저를 감지하지 못한 것입니다. 다음 중 하나를 설치하세요:

• Google Chrome: https://www.google.com/chrome/

• Microsoft Edge: https://www.microsoft.com/edge

• Chromium: https://www.chromium.org/getting-involved/download-chromium/

또는 agent-browser를 통해 설치하세요:

npx agent-browser install

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• one_extractA
• one_mapB
• one_scrapeC
• one_searchB