agentSearcher MCP server
2026년 10월 27일 커밋가벼운 셀프 호스팅 프로세스를 통해 AI agent가 웹 검색, 콘텐츠 추출, 웹사이트 크롤링 및 사이트 구조 매핑을 수행할 수 있도록 합니다.
다른 이름 peakQuick/agentSearcher
- 스타
- 3
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 27일
- 라이선스
- AGPL-3.0
agentSearcher MCP란?
가벼운 셀프 호스팅 프로세스를 통해 AI agent가 웹 검색, 콘텐츠 추출, 웹사이트 크롤링 및 사이트 구조 매핑을 수행할 수 있도록 합니다.
프로젝트 README에서 생성된 요약
agentSearcher MCP server 정보
클라우드 기반 API 키에 의존하지 않고 AI agent에게 웹 검색, 추출 및 크롤링 기능을 제공하는 것이 agentSearcher의 주요 기능입니다. 이 셀프 호스팅 솔루션은 단일 Python 프로세스로 실행되므로 SearXNG 또는 Firecrawl과 같은 여러 서비스를 포함하는 복잡한 설정에 대한 가벼운 대안이 됩니다. CPU만 사용하는 로컬 머신에서 작동하도록 설계되었으며, 일정 시간 활동이 없으면 브라우저와 랭킹 모델을 언로드하여 메모리를 자동으로 관리합니다.
개발자는 stdio 또는 streamable HTTP 연결을 통해 MCP를 사용하여 이 서버를 워크플로우에 통합할 수 있습니다. web_search, web_extract, web_crawl, web_map을 포함한 특정 도구를 제공하며, 이는 쉬운 마이그레이션을 위해 Tavily API 형식에 맞춰 이름을 변경할 수 있습니다. 시스템은 headless Chromium을 통해 JavaScript가 많은 페이지를 처리하고 PDF 파일의 텍스트 레이어를 읽을 수 있습니다. 다국어 cross-encoder와 BM25 랭킹을 사용하여 가장 관련성 높은 콘텐츠 청크만 전달함으로써 응답이 작은 컨텍스트 창 내에 들어오도록 보장합니다.
활용 사례
- 1대상 웹 검색 수행AI agent에게 DuckDuckGo 또는 Bing과 같은 여러 검색 엔진에서 특정 정보를 찾도록 요청합니다.
- 2특정 URL에서 콘텐츠 추출분석을 위해 웹페이지나 PDF 문서에서 관련 텍스트를 가져오도록 agent에게 지시합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
AGENTSEARCHER_API_KEYS
| 이름 | 설명 | 유형 |
|---|---|---|
| AGENTSEARCHER_API_KEYS | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능peakquick/agentsearcher is public and reachablegithub.com/peakquick/agentsearcher ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-27github.com/peakquick/agentsearcher ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기agentsearcher
Lightweight local web retrieval for AI agents: search, extract, crawl and map in one CPU-only process. No cloud keys.
An agent that works with the web needs to find pages, read them (including JavaScript pages and PDFs) and sometimes walk a whole site. agentsearcher does all of it in one Python process and returns only the passages that matter, sized for a small context window. It is available as an MCP server, an HTTP API (Tavily-compatible) and a CLI, with a dashboard in the browser.
Contents
Why
Self-hosted web retrieval usually means assembling several services: a metasearch engine such as SearXNG for search, a crawler such as Crawl4AI for page content, or a self-hosted Firecrawl, which runs as an API plus a browser service, Redis, RabbitMQ and Postgres. agentsearcher is one process instead:
- Light. ~75 MB idle; ~380 MB while ranking with the model; Chromium only starts for pages that need it. The model and the browser are unloaded after 2 minutes idle. Measured on a laptop i7-7500U with 7.5 GB RAM, no GPU (details).
- Search and reading together. One query fetches, renders, cleans and ranks the result pages, so the agent gets relevant passages instead of snippets or whole pages.
- Made for agents. Responses fit a small context window; reprints and near-duplicates are dropped; results the search engines agree on rank higher than SEO pages one engine pushes up.
- Easy to run.
pipx installordocker compose up. Nothing to configure to get started.
Features
- MCP server (stdio, or streamable HTTP at
/mcpon the API port) with the toolsweb_search,web_extract,web_crawlandweb_map. An env flag renames them totavily_*. - JavaScript pages: when a plain fetch isn't enough, the page is rendered in headless Chromium.
- PDF: the text layer is read. No OCR.
sitemap.xml,robots.txtandllms.txtare used by map/crawl, and.mdversions of pages by extract/crawl. Sites without these files work too.- Reprints and near-duplicate chunks are dropped (
dedup), and results can be capped per domain (max_per_domain). - SSRF protection: localhost and private networks are blocked by default.
- Response size is capped to fit a small context window. The model and the browser are unloaded after a period of inactivity.
- Pages and search results are cached for 15 minutes; optional block/lower/raise rules per domain.
- Dashboard at
/: request and page counters, CPU and memory (with the browser), recent requests, and a playground for search, extract, crawl and map. - Drop-in for Tavily clients:
/search,/extract,/crawl,/map,/usagerespond in the Tavily API format, so existing clients only change the base URL. Covered by tests with the officialtavily-pythonclient.
How it works
query ─► search engines (ddgs: duckduckgo, yahoo, yandex, brave, mojeek, bing; optional SearXNG)
─► fetch pages with curl_cffi (Chrome TLS fingerprint)
└─ empty page / SPA / anti-bot / text doesn't match snippet ─► patchright Chromium
─► trafilatura → markdown (PDF → text layer) ─► ~600-char chunks
─► BM25 ─► multilingual cross-encoder (ONNX int8, CPU)
─► dedup ─► only the best chunks of each page go into the response
Details: docs/how-it-works.md.
Installation
Docker (Chromium and the model are inside the image):
git clone https://github.com/peakQuick/agentSearcher.git && cd agentSearcher
docker compose up -d --build # API and MCP at http://127.0.0.1:8484, MCP at /mcp
Settings go under environment: in compose.yaml. On macOS and Windows, Docker Desktop runs a VM, which costs extra RAM; there, the pipx install below is lighter.
pipx (no venv to manage; pipx is in most package managers: apt install pipx, brew install pipx, pacman -S python-pipx):
pipx install git+https://github.com/peakQuick/agentSearcher
agentsearcher setup # one time: Chromium (~/.cache/ms-playwright) and the ~120 MB reranker (~/.cache/huggingface)
agentsearcher serve
Update with pipx upgrade agentsearcher. On a bare Linux server, agentsearcher setup --with-deps also installs Chromium's system libraries (needs root).
From source (development):
git clone https://github.com/peakQuick/agentSearcher.git && cd agentSearcher
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/agentsearcher setup
Below, agentsearcher means the installed command (.venv/bin/agentsearcher for a source install).
Quick start
CLI
agentsearcher search "what's new in python 3.14"
agentsearcher extract https://react.dev/learn -q "useState"
agentsearcher map https://docs.python.org/3/
HTTP API
agentsearcher serve # dashboard: open http://127.0.0.1:8484/
curl -s localhost:8484/search -H 'Content-Type: application/json' \
-d '{"query": "python asyncio tutorial", "max_results": 3}'
With tavily-python:
from tavily import TavilyClient
client = TavilyClient(api_key="local", api_base_url="http://127.0.0.1:8484")
print(client.search("python asyncio tutorial", max_results=3)["results"][0]["url"])
MCP
With serve or Docker running, HTTP clients and web UIs connect to http://127.0.0.1:8484/mcp:
claude mcp add --transport http agentsearcher http://127.0.0.1:8484/mcp
Or let the client start its own server over stdio:
claude mcp add agentsearcher -- agentsearcher mcp
Other clients: docs/mcp.md.
Configuration
The defaults work as is. Settings are environment variables with the AGENTSEARCHER_ prefix:
AGENTSEARCHER_API_KEYS=change-me agentsearcher serve # pipx / source
With Docker, put them under environment: in compose.yaml; for MCP over stdio, in the client's env block. GET /stats shows the values in effect (secrets hidden).
The ones people usually change: API_KEYS (before opening the server to a network), PROXY_URL (search engines block your IP), LLM_BASE_URL (answers with include_answer), MAX_REQUESTS / MAX_RENDERS (a machine with little RAM). All variables and ready-made recipes: docs/configuration.md.
Search depth
| mode | what it does | warm latency* |
|---|---|---|
ultra-fast |
search engine snippets only, no pages fetched | ~1 s |
fast |
pages without the browser, BM25 ranking | 3–4 s |
basic |
+ browser for JS and anti-bot pages, + cross-encoder | 6–9 s |
advanced |
+ more candidates, favor_recall, stricter about "empty" pages |
7–10 s |
* i7-7500U, 5 results. The first request takes longer: ~1.5 s to load the model and ~1 s to start the browser.
Documentation
| doc | what's inside |
|---|---|
| CLI | commands, flags and how to read the log |
| HTTP API | endpoints, parameters, responses and errors |
| MCP | tools and client setup |
| Configuration | environment variables |
| How it works | pipeline, browser, ranking, crawling, PDF, dedup, memory |
| Security | SSRF protection |
| Limitations | known limitations and possible problems |
Development
.venv/bin/ruff check .
.venv/bin/python -m pytest -m "not live" # offline: local fixture sites (SPA, challenge, PDF, sitemap...), tavily-python contract
.venv/bin/python -m pytest -m live # needs internet: tavily-python search at every search_depth
License
Copyright (C) 2026 peakQuick
GNU Affero General Public License v3.0. If you modify this project and let others use it over a network, you must make the source code of your modified version available to those users.
agentSearcher MCP 질문
agentSearcher는 웹 검색을 위해 API 키가 필요한가요?
아니요, 클라우드 키 없이 작동하도록 설계되었으며 DuckDuckGo, Yahoo, Bing과 같은 검색 엔진을 사용합니다.
JavaScript가 많은 웹사이트나 PDF를 처리할 수 있나요?
네, headless Chromium을 사용하여 JavaScript 페이지를 렌더링하며 PDF 파일의 텍스트 레이어를 읽을 수 있습니다.
메모리를 얼마나 사용하나요?
매우 가볍습니다. 유휴 상태에서는 약 75 MB를 사용하며, 모델을 사용하여 랭킹을 수행할 때는 약 380 MB를 사용합니다.