OneSearch MCP Server
🚀 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: Firecrawl MCP 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 비용이 발생하지 않습니다.
마이그레이션 단계:
Chromium 브라우저 설치 (필수 구성 요소 참조)
환경 변수에서
FIRECRAWL_API_URL및FIRECRAWL_API_KEY제거최신 버전으로 업데이트:
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-mcpDocker 사용
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:latestClaude 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';검색 제공업체 구성
제공업체 | API 키 필요 | API URL 필요 | 참고 |
| 아니요 | 아니요 | 무료, 브라우저 자동화 사용 |
| 아니요 | 아니요 | 무료, API 키 불필요 |
| 선택 사항 | 예 | 자체 호스팅 메타 검색 엔진 |
| 예 | 아니요 | |
| 예 | 아니요 | |
| 예 | 예 (검색 엔진 ID) | |
| 예 | 아니요 | |
| 예 | 아니요 | |
| 예 | 아니요 |
다른 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 파일을 참조하세요.
Available Tools
4 toolsone_extractA
Fetch and preprocess page content from one or more URLs. Returns cleaned text blocks that can be passed to downstream tools or models.
Inputs: urls (required).
one_mapA
Discover URLs from a starting point by loading a page in the browser and extracting links from its HTML.
Inputs: url (required), limit, search, includeSubdomains.
one_scrapeA
Scrape a single webpage and return markdown, HTML, links, or a screenshot. Supports navigation timeout, TLS verification control, full-page screenshots, bounded pre-scrape actions, and advanced executeJavascript only when allowExecuteJavascript is true.
Inputs: url (required), actions, formats, timeout, +3 more.
one_searchB
Search and retrieve content from web pages. Returns SERP results by default (url, title, description).
Inputs: query (required), limit, language, timeRange, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct core function: search returns SERP results, extract preprocesses multiple URLs, scrape handles single-page advanced operations, and map discovers links. There is minor overlap between extract and scrape for fetching page content, but their descriptions make the intended use cases clear.
All tool names follow the consistent pattern 'one_' prefix followed by a lowercase action verb (search, extract, scrape, map), with underscores between words. No mixed conventions or camelCase.
Four tools is well within the ideal range for a focused search/scraping server. Each tool covers a distinct aspect of web research, making the set feel appropriately scoped without being bloated.
The tool set covers the primary workflows: searching, extracting content, single-page scraping with advanced options, and link discovery. Minor gaps exist, such as no dedicated batch scraping tool, but the combined functionality handles most common use cases.
Maintenance
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Free web search for AI agents. No API key required. Hosted MCP in active development.
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Related MCP Servers
- FlicenseCqualityCmaintenanceBuilt as a Model Context Protocol (MCP) server that provides advanced web search, content extraction, web crawling, and scraping capabilities using the Firecrawl API.41-
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to perform advanced web scraping, crawling, searching, and data extraction through the Firecrawl API.9MIT
- AlicenseAqualityBmaintenanceA Model Context Protocol server that provides real-time web search capabilities to AI assistants through pluggable search providers, currently integrated with the Brave Search API.534 npm16MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables web scraping, crawling, and content extraction capabilities through integration with Firecrawl.82MIT