free-search-mcp

👁 License
👁 Python
👁 MCP

로컬 우선, API 키가 필요 없는 Model Context Protocol 서버입니다. 모든 LLM(Claude, GPT, 로컬 Ollama 등)이 웹을 검색하고, 페이지를 가져와 정리하며, 문서를 읽을 수 있는 기능을 제공합니다. 검색 API를 위해 별도로 가입할 필요가 없습니다.

이 서버는 여러 오픈 소스 MCP의 핵심 아이디어를 하나의 Python 패키지로 통합하고, 각 프로젝트에서 부족했던 LLM 사용 편의성과 신뢰성을 보완했습니다.

research("how does reciprocal rank fusion work", depth=3)
 ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, mojeek, startpage · sources: 3 · ~3,400 tokens_

## Sources
- [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
- [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
- [3] RRF explained in 4 mins — Medium — <https://…>

## Documents
…full Markdown bodies of each page, ready for the LLM to read…

단 한 번의 도구 호출. 세 가지 소스. API 키 불필요. 검색을 위한 OPENAI_API_KEY와 같은 번거로운 절차도 없습니다.

왜 이 프로젝트가 필요한가요?

기존의 검색 MCP들은 각각 한 가지 기능은 잘 수행하지만, 보통은 그 모든 기능이 필요합니다:

여기서 "LLM 튜닝"이란 다음을 의미합니다: 마크다운 우선 출력, 토큰 추정, 단락 경계에서의 스마트한 잘림, 모델이 올바른 도구를 선택하도록 돕는 "Best for / Not for / Returns / Common mistakes" 독스트링, 실행 가능한 오류 힌트, MCP 프롬프트 및 리소스 템플릿, 그리고 검색→가져오기→가져오기→가져오기를 단일 턴으로 압축하는 원샷 research() 기능.

"Trafilatura"는 trafilatura를 사용하여 주요 콘텐츠를 추출함을 의미합니다. 이는 Bevendorff 2023 ROUGE 벤치마크에서 우승한 도구입니다(단순 보일러플레이트 제거 시 ~0.55 대비 ~0.85). 가져온 각 페이지는 author, published_date, sitename을 무료로 반환합니다.

"필터"는 검색/조사 시 freshness, include_domains, exclude_domains, category (news/pdf/github/paper/forum/blog), include_text, exclude_text를 지원함을 의미합니다.

Related MCP server: TOOL4LM

도구

또한 2개의 MCP 프롬프트 (Research thoroughly, Fact-check claim)와 캐시된 페이지를 다시 가져오지 않고 컨텍스트로 불러올 수 있는 리소스 템플릿 (cache://page/{url})이 포함되어 있습니다.

필터 (search / research)

모든 도구는 기본적으로 format="markdown"을 사용합니다. 이는 JSON보다 읽기 쉽고 토큰을 약 40% 적게 사용하며, 출처와 토큰 예산 헤더를 포함합니다. 구조화된 데이터가 필요하면 format="json"을 전달하세요.

도구 주석

모든 도구는 올바른 readOnlyHint, idempotentHint, openWorldHint 주석을 제공하여 MCP 클라이언트가 이를 레이블링하고 권한이 필요한 작업을 제어할 수 있도록 합니다.

엔진

기본 세트 (모두 신뢰할 수 있으며 반복 호출 시 캡차 없음): duckduckgo, mojeek, startpage.

옵트인 (헤드리스 클라이언트에 간헐적인 챌린지 발생): brave, bing, baidu.

Brave/Bing/Baidu는 몇 번의 호출 후 헤드리스 브라우저를 차단합니다(PoW 캡차, "something went wrong" 페이지, 리다이렉트 래퍼 등). 기본 엔진으로 원하는 결과를 찾을 수 없을 때만 engines=["brave"] 등을 전달하세요.

설치

git clone https://github.com/ymylive/free-search-mcp.git
cd free-search-mcp
uv sync
uv run playwright install chromium

독립형 서버로 실행 (stdio 전송):

uv run search-mcp

라이브 테스트 실행 (실제 웹에 접속 — 환경 변수 설정 필요):

SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v

오프라인 테스트는 기본적으로 실행되며 네트워크에 접속하지 않습니다.

Claude Desktop에 연결

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 해당 플랫폼의 동일한 경로에 다음을 추가하세요:

{
 "mcpServers": {
 "search": {
 "command": "uv",
 "args": ["--directory", "/absolute/path/to/free-search-mcp", "run", "search-mcp"]
 }
 }
}

Claude Desktop을 재시작하세요. 위의 7가지 도구가 도구 서랍에 나타납니다.

다른 클라이언트에 연결

이 서버는 stdio를 통해 표준 MCP를 사용합니다. MCP를 지원하는 모든 클라이언트에서 작동합니다:

• Claude Code (claude mcp add search uv --directory /…/free-search-mcp run search-mcp)

• Cursor / Continue / Cline (위의 JSON 스니펫 사용)

• 공식 MCP SDK를 사용하는 커스텀 Python / TypeScript 클라이언트

설정

모든 설정은 SEARCH_MCP_ 접두사가 붙은 환경 변수로 재정의할 수 있습니다:

아키텍처

 ┌─────────────────────────────────────────────────────┐
 │ FastMCP server (stdio) │
 │ tools: search / research / fetch / fetch_batch / │
 │ read_doc / cache_search / engines │
 └────────────┬────────────────────────────────────────┘
 │
 ┌────────────▼────────────┐ ┌────────────────────────┐
 │ aggregator │ │ fetcher │
 │ - parallel engines │ │ - httpx fast path │
 │ - reciprocal rank │ │ - playwright fallback │
 │ fusion │ │ - markdownify │
 │ - search cache (FTS5) │ │ - page cache (FTS5) │
 └────┬────────────────────┘ └────────────┬───────────┘
 │ │
 ┌────▼─────────────────┐ ┌──────────────▼─────────────┐
 │ engines/ │ │ browser pool │
 │ duckduckgo.py │ │ - persistent context │
 │ mojeek.py │ │ - stealth init script │
 │ startpage.py │ │ - shared cookies │
 │ brave.py (opt) │ │ - semaphore-bounded pages│
 │ bing.py (opt) │ └────────────────────────────┘
 │ baidu.py (opt) │
 └──────────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ documents/ │ │ ratelimit │
 │ pypdf, python-docx, │ │ token bucket │
 │ markdownify │ │ per engine │
 └────────────────────────────┘ └──────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ formatting │ │ research │
 │ token estimate │ │ composed │
 │ smart truncation │ │ workflow │
 │ markdown renderers │ │ │
 └────────────────────────────┘ └──────────────────┘

엔진 어댑터 패턴

src/search_mcp/engines/의 각 엔진은 다음을 구현합니다:

class Engine:
 name: str
 needs_browser: bool # Force Playwright?
 wait_selector: str | None # CSS to wait for in browser mode

 def build_url(self, query: str, max_results: int) -> str: ...
 def parse(self, html: str) -> list[SearchResult]: ...

기본 클래스는 전송(httpx → Playwright 폴백), 속도 제한, 그리고 HTTP가 결과 대신 캡차 셸을 반환하는 경우(브라우저를 통한 자동 재시도)를 처리합니다.

크레딧

이 프로젝트는 다음 프로젝트들의 도움을 받았습니다:

• mrkrsl/web-search-mcp — 스마트한 httpx-then-Playwright 가져오기 전략, 다중 엔진 폴백 체인

• Aas-ee/open-webSearch — 다중 엔진 범위(Bing/DDG/Baidu/Brave/Startpage)

• VincentKaufmann/noapi-google-search-mcp — 탐지 방지 패턴(navigator.webdriver, UA, 쿠키), SQLite FTS5 캐시 아이디어, 다중 형식 read_document

• nickclyde/duckduckgo-mcp-server — 엔진별 속도 제한, LLM 친화적인 콘텐츠 정리

• Mojeek — User-Agent를 차단하지 않는 독립적인 검색 인덱스

• Model Context Protocol 및 공식 Python SDK

라이선스

MIT — LICENSE를 참조하세요.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cache_searchA
• compareA
• enginesA
• extract_structuredA
• fetchA
• fetch_batchA
• read_docA
• researchA