wigolo: API 키 없이 로컬에서 동작하는 AI 에이전트용 웹 검색 MCP 서버

읽을거리&정보공유
, , , , ,
1

wigolo: API 키 없이 로컬에서 동작하는 AI 에이전트용 웹 검색 MCP 서버
wigolo: API 키 없이 로컬에서 동작하는 AI 에이전트용 웹 검색 MCP 서버1536×1024 227 KB

wigolo 소개

AI 코딩 에이전트에게 웹은 필수 도구가 됐지만, 대부분의 검색·크롤링 도구는 클라우드 API 키를 요구하고 쿼리마다 요금이 붙습니다. 에이전트는 한 번에 답을 얻기보다 여러 질의를 몰아서 던지는 특성이 있어, 이 과금 구조는 사용량이 늘수록 부담이 커집니다. wigolo는 이 지점을 다르게 접근합니다. 검색·수집 엔진을 사용자의 로컬 머신에서 돌려, API 키 없이 쿼리당 비용 0으로 웹에 접근하도록 만든 도구입니다.

wigolo는 웹과 관련된 작업을 하나의 표면으로 묶습니다. 검색(search), 페이지 가져오기(fetch), 크롤링(crawl), 구조화 추출(extract), 캐시(cache), 유사 문서 탐색(find_similar), 리서치(research), 그리고 자율 수집 루프(agent)까지 열 개의 도구를 제공합니다. 이 도구들은 에이전트가 실행되는 곳 어디서든 함께 동작합니다. 코딩 에이전트 옆의 MCP 서버로, 자체 호스팅 에이전트가 있는 서버의 REST·MCP 엔드포인트로, 또는 SDK를 통해 애플리케이션에 임베드하는 방식으로 붙일 수 있습니다.

핵심 도구들은 API 키가 필요 없고, wigolo가 다루는 데이터는 ~/.wigolo/ 밖으로 나가지 않습니다. 검색 결과의 순위 재조정(reranking)과 임베딩(embedding)은 온디바이스(on-device) 모델로 로컬에서 처리되며, LLM은 리서치 결과를 문장으로 합성할 때만 선택적으로 사용합니다. 이 게시물에서는 wigolo가 제공하는 도구 구성, 에이전트에게 돌려주는 결과의 형태, 설계 원칙, 그리고 설치·사용법을 정리합니다.

wigolo가 제공하는 10가지 웹 도구

wigolo의 도구들은 MCP 호출뿐 아니라 터미널(wigolo search "…" --json), NDJSON 파이핑이 가능한 대화형 셸(wigolo shell), REST, 그리고 SDK로도 모두 실행됩니다. 각 도구가 하는 일은 다음과 같습니다.

도구 하는 일
:magnifying_glass_tilted_right: search 18개 검색 엔진을 직접 어댑터로 붙여 멀티 엔진 검색을 수행하고, 순위 융합(rank fusion)과 ML 리랭킹을 거쳐 결과별 점수를 설명 가능한 형태로 반환합니다. 질의를 배열로 넘기면 병렬로 폭을 넓힙니다.
:page_facing_up: fetch 하나의 URL을 단계적 라우터로 가져옵니다. 일반 HTTP로 시작해 안티봇 챌린지나 SPA 껍데기를 만나면 헤드리스 브라우저 엔진으로 자동 승격합니다. 정리된 마크다운과 메타데이터, 링크를 돌려주며 PDF와 페이지 조작(클릭·입력·스크롤·스크린샷)도 처리합니다.
:spider_web: crawl BFS·DFS·사이트맵·맵 전용 방식의 다중 페이지 크롤링입니다. 도메인별 요청 속도 제한과 robots.txt 준수, 보일러플레이트 중복 제거를 포함합니다.
:puzzle_piece: extract 페이지에서 표·메타데이터·JSON-LD·브랜드 정보·명명된 스키마(Article/Recipe/Product 등) 또는 임의의 커스텀 JSON 스키마로 구조화된 데이터를 뽑아냅니다.
:floppy_disk: cache 이미 본 모든 것을 키워드 또는 하이브리드 시맨틱 방식으로 다시 질의합니다. 통계·초기화·변경 감지 기능도 함께 제공합니다.
:magnet: find_similar URL이나 개념과 유사한 페이지를 키워드·시맨틱·실시간 웹의 3방향 융합으로 찾습니다.
:brain: research 질문을 하위 질의로 분해한 뒤 여러 소스를 가져와 인용이 달린 보고서로 합성합니다(또는 호스트 LLM이 작성할 수 있는 구조화된 브리프를 반환).
:robot: agent 계획 → 검색 → 가져오기 → 추출 → 합성으로 이어지는 자율 수집 루프입니다. 단계 로그, 시간 예산(time budget), 선택적 출력 스키마를 지원합니다.
:repeat_button: diff + :stopwatch: watch 지난 방문 이후 페이지가 정확히 무엇이 바뀌었는지 보여주고, 요청 시 다시 확인해 변경 내용을 웹훅으로 전달합니다.

검색·가져오기·크롤링·추출·캐시·유사 문서 탐색은 API 키 없이 동작합니다. 반면 research 와 agent, 그리고 search format=answer 는 인용이 달린 완성 답변을 문장으로 쓰기 위해 LLM을 사용합니다. LLM을 붙이지 않으면 원시 브리프와 근거를 돌려주어 에이전트가 직접 답을 조립하게 합니다. 무료 Gemini 키를 넣으면 완성된 답변이 되고, anthropic·openai·groq 같은 다른 제공자도 쓸 수 있으며, ollama(또는 OpenAI 호환 URL)로 완전히 로컬·키 없이 유지할 수도 있습니다.

wigolo가 돌려주는 결과의 구조

wigolo가 에이전트에게 돌려주는 검색 결과는 그 자체로 에이전트가 행동에 쓸 수 있는 근거(evidence)입니다. 각 결과는 원문의 정확한 위치에 고정된 그대로의 발췌(verbatim excerpt), 에이전트가 인용할 수 있는 인용 ID(citation_id), 그리고 검토 가능한 점수를 함께 담습니다. 점수는 최종값과 시맨틱·어휘·엔진 합의(engine_consensus) 항목으로 분해되어, 왜 그 순위가 나왔는지 들여다볼 수 있습니다.

아래는 wigolo가 하나의 실제 질의("postgres logical vs streaming replication")에 대해 돌려준 결과를 해부한 그림입니다. 결과의 점수 분해, 실시간 엔진 텔레메트리, 성능이 떨어진 백엔드, 그리고 자체 스코어러가 약한 결과로 걸러낸 항목이 한 번의 호출 안에 모두 들어 있습니다.

wigolo 결과의 구조를 해부한 다이어그램: 설명 가능한 점수 분해와 엔진 텔레메트리
wigolo 결과의 구조를 해부한 다이어그램: 설명 가능한 점수 분해와 엔진 텔레메트리1840×1336 312 KB

여기서 눈여겨볼 점은 wigolo가 실패와 저품질도 결과의 일부로 드러낸다는 것입니다. 약한 결과는 자체 스코어러가 정크(junk)로 표시하고, 실패한 엔진은 그대로 보고되며, 오래된 캐시는 라벨이 붙습니다. 봇 차단 페이지를 읽지 못하면 챌린지 껍데기를 콘텐츠인 척 반환하지 않고 blocked_by_challenge 실패로 명시합니다. 덕분에 에이전트는 자신이 딛고 선 근거가 어떤 상태인지 항상 알 수 있습니다.

wigolo가 기존 도구와 다른 점

개발자는 wigolo를 유료 도구의 무료 대체품이 아니라 그 품질에 맞추려 만든 에이전트용 웹 계층이라고 소개합니다. 차별점으로 내세우는 것은 다음과 같습니다.

  • 에이전트를 위한 설계: 하나의 MCP 호출이 여러 엔진에 걸쳐 여러 질의를 병렬로 펼칩니다. 직렬로 도는 호스트 도구 루프로는 재현하기 어려운 방식이며, 모든 결과에 결과별 점수가 투명하게 붙고 출력은 예산을 의식(budget-aware)합니다.
  • 정직한 출력: 오래된 캐시, 실패한 가져오기, 성능이 떨어진 백엔드, 잘린 출력이 결과에 그대로 표시됩니다.
  • 쿼리당 비용 0: 기본 검색은 직접 어댑터로 공개 엔진과 통신하고, 리랭커와 임베딩은 온디바이스에서 돕니다. 모든 응답이 캐시되어 같은 질문을 다시 던지면 즉시, 비용 없이 답합니다.
  • 기본값이 프라이버시: 캐시·임베딩·모델·설정이 모두 ~/.wigolo/ 아래에 있습니다. 합성용 LLM을 명시적으로 켜지 않는 한 어떤 것도 제3자에게 가지 않습니다.

개발팀은 다른 검색·크롤링 도구와의 기능 비교도 함께 공개하고 있습니다(2026년 7월 기준, 각 벤더의 현재 상태는 문서 확인 필요).

기능 wigolo Firecrawl Exa Tavily
멀티 엔진 웹 검색 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:
가져오기 및 구조화 추출 :white_check_mark: :white_check_mark: :white_check_mark: :white_check_mark:
사이트 전체 크롤링·맵 :white_check_mark: :white_check_mark: — :white_check_mark:
바이트 오프셋에 고정된 그대로의 발췌 :white_check_mark: — — —
설명 가능한 결과별 점수 분해 :white_check_mark: — — —
로컬 영구 메모리(오프라인 재질의) :white_check_mark: — — —
질의 데이터가 로컬에 유지 :white_check_mark: — — —
API 키·계정 불필요 필요 필요 필요
쿼리당 비용 $0 종량제 종량제 종량제

wigolo의 아키텍처

wigolo는 하나의 Node 프로세스가 MCP(stdio 위의 JSON-RPC)를 말하는 구조입니다. 무거운 작업은 모두 로컬에서 지연 로딩(lazy-load)되므로, 키 없이 설치해도 쓰지 않는 부분에는 비용을 치르지 않습니다. 이 설계에서 반복적으로 강조되는 원칙은 다음 세 가지입니다.

첫째, 코드가 모델을 이깁니다. 정규화·순위 융합·중복 제거·스키마 매칭 같은 결정적(deterministic) 작업은 LLM 밖에서 처리하고, 모델은 판단이 필요한 자리에만 선택적으로, 요청당 상한을 두고 씁니다. LLM이 채운 필드는 원문과 대조해 근거가 없으면 무효화(null)합니다.

둘째, 신호 기반 라우팅입니다. fetch 의 단계적 사다리는 도메인을 추측하는 대신 SPA 마커, 챌린지 본문, 얇은 콘텐츠 같은 관측 가능한 신호에 따라 실제 브라우저로 승격합니다. 도메인별로 학습하고, 사이트가 더 이상 필요로 하지 않으면 학습을 되돌리며, wigolo tune list 로 무엇을 학습했는지 확인할 수 있습니다.

셋째, 브라우저처럼 페이지를 읽습니다. 단계적 가져오기는 도메인별로 통과 권한을 재사용하면서 robots.txt를 지키고 도메인별 속도 제한을 둡니다. 벽이 계속 서 있으면 그 실패를 라벨링해 보고합니다.

wigolo 설치 및 사용법

Node 20 이상과 macOS·Linux·Windows에서 약 1.5GB의 여유 디스크가 필요합니다. 기본 init 은 로컬 엔진을 설정합니다. 브라우저 엔진과 온디바이스 모델을 내려받고, 헬스 체크를 돌린 뒤 각 구성요소 상태를 보고합니다.

npx wigolo init                              # 로컬 엔진 설정 (모든 시스템)
npx wigolo init --agents=claude-code,cursor  # 설정 + 자주 쓰는 에이전트 연결을 한 명령으로

--agents 는 claude-code·cursor·codex·gemini-cli·vscode·windsurf·zed·antigravity 를 쉼표로 받아 각 에이전트의 MCP 설정과 지침을 자동으로 써 줍니다. 그 밖의 MCP 클라이언트나 에이전트 프레임워크, 자체 호스팅 에이전트는 자신의 MCP 설정에 npx -y wigolo 를 등록하면 됩니다. 설치가 정상인지는 언제든 npx wigolo doctor 로 점검할 수 있습니다.

리서치·에이전트 도구의 답변 품질을 올리려면 합성용 LLM 제공자를 지정합니다. 무료 Gemini 키로 충분합니다.

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key>      # aistudio.google.com/apikey 에서 무료 발급

MCP 클라이언트가 필요 없다면 wigolo serve 로 REST API를 띄울 수 있습니다. 하나의 프로세스가 REST와 MCP 전송을 함께 노출하며, 루프백(127.0.0.1)은 열려 있고 루프백 밖으로 바인딩하면 토큰이 필요합니다.

wigolo serve                          # 127.0.0.1:3333

curl -sX POST http://127.0.0.1:3333/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"local-first software","max_results":5}'

애플리케이션에 임베드하려면 TypeScript(npm install wigolo-sdk)와 Python(pip install wigolo) SDK를 쓸 수 있습니다. 두 SDK 모두 실행 중인 데몬을 찾거나 새로 띄우는 임베디드 로컬 모드를 제공합니다.

from wigolo import local_client

with local_client() as client:                          # 정상 데몬을 재사용하거나 새로 띄움
    res = client.search(query="local-first web search", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

또한 LangChain(wigolo-langchain), CrewAI(wigolo-crewai), LlamaIndex(wigolo-llamaindex), Vercel AI SDK(wigolo-vercel-ai-sdk) 래퍼로 기존 프레임워크에 그대로 붙일 수 있고, ghcr.io/knockoutez/wigolo 도커 이미지로도 실행할 수 있습니다.

wigolo의 라이선스

wigolo는 GNU AGPL-3.0 라이선스로 공개되어 있습니다. AGPL은 강한 카피레프트 라이선스로, 소스를 수정해 배포하거나 네트워크 서비스 형태로 제공할 때 파생 저작물의 소스 코드도 동일한 AGPL로 공개해야 합니다. 사내 도구나 개인 용도로 쓰는 데에는 제약이 크지 않지만, wigolo를 포함한 서비스를 외부에 제공할 계획이라면 이 조건을 먼저 확인하는 것이 좋습니다. 저장소의 LICENSE 파일과 상표 관련 안내인 TRADEMARK.md 에 자세한 내용이 있습니다.

:house: wigolo 공식 홈페이지

:books: wigolo 문서

:github: wigolo 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. :smiley:

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

SurfSense: 실시간 웹 데이터 커넥터를 갖춘 오픈소스 NotebookLM 대안