wigolo: local-first MCP web search for AI agents
/wigolo
wigolo is a free MCP server that gives an AI coding agent web search, fetch, crawl, extract, and cache tools with no API key and no per-query bill. It backs that up: the core six tools run entirely on your own machine, and a repeat query is served from local cache instead of billed again. The catch: `research` and `agent` still need a free LLM key to write a synthesized answer, and the project is public beta, not v1.
What wigolo is and what problem it solves
wigolo is an MCP (Model Context Protocol) server, REST API, and SDK giving an AI agent one surface for web search, fetch, crawl, extract, cache, find-similar, and research. It's built for developers wiring a coding agent like Claude Code or Cursor into the web without paying per query to Firecrawl, Exa, or Tavily. Everything lives under `~/.wigolo/`, using 18 direct search-engine adapters and rank fusion instead of one paid aggregator API.
The 10 tools: search, fetch, crawl, extract, cache, and more
- ✓search — 18 direct search-engine adapters using rank fusion and ML reranking, along with an explainable per-result score; give a query array to achieve parallel breadth
- ✓fetch — a tiered router that only escalates from plain HTTP to a headless browser when it hits an anti-bot challenge or SPA shell, returning clean markdown, metadata, and links
- ✓crawl — an API-free web crawler: BFS, DFS, sitemap, or map-only multi-page crawling with per-domain rate limits and robots.txt respect
- ✓extract — pulls tables, metadata, JSON-LD, brand identity, or named schemas like Article/Recipe/Product from a page, or any custom JSON Schema you supply
- ✓cache and find_similar — query everything wigolo has already indexed by keyword or hybrid semantic search, or surface pages similar to a URL via 3-way fusion
- ✓research — decomposes a question into sub-queries, fetches sources, and synthesizes a cited report once an LLM key is set
- ✓agent — a full plan → search → fetch → extract → synthesize loop, including a step log, time budget, and optional output schema
- ✓watch for differences — track precisely what has changed on a page since your previous visit, check again when needed on demand, and push updates to a webhook
Installing wigolo in one command
Run `npx wigolo init` to set up the local engine on macOS, Linux, or Windows — it needs Node 20 or newer and about 1.5 GB of free disk, downloads the browser engine and on-device models, and reports each component's health as it goes. Add `--agents=claude-code,cursor` (or any combination of codex, gemini-cli, opencode, vscode, windsurf, zed, antigravity) to wire a coding agent's MCP config in the same run. `init` is unattended by default, so it's safe to run in CI, and `--no-warmup` defers the model downloads until first use. Check the result anytime with `npx wigolo doctor`, and remove everything cleanly with `npx wigolo config --uninstall --yes`. Docker images are published at `ghcr.io/knockoutez/wigolo` and, mirrored, on Docker Hub as `towhid69420/wigolo`.
Wiring wigolo into your AI agent or framework
For a coding agent, `npx wigolo init --agents=<name>` writes the MCP config directly. Any other MCP client, agent framework, or self-hosted agent instead registers `npx -y wigolo` in its own MCP config. Run `wigolo serve` to expose the same ten tools as a plain-JSON REST API on `127.0.0.1:3333` — binding past loopback requires a bearer token — with `/mcp` and `/sse` serving remote MCP clients from that same port. To embed wigolo directly, `npm install wigolo-sdk` or `pip install wigolo` gives a typed client (`createLocalClient()` / `local_client()`) that finds or spawns the local daemon itself, no separate `serve` step needed. LangChain, CrewAI, LlamaIndex, and the Vercel AI SDK each get a dedicated wrapper package — `wigolo-langchain` adds a `BaseRetriever` over search/find_similar for RAG retrieval, `wigolo-crewai` hands a crew the full tool set, and `wigolo-llamaindex` loads fetched pages as documents. `research`, `agent`, and `search format=answer` only write a synthesized answer once `WIGOLO_LLM_PROVIDER` points at a configured key.
What makes wigolo worth using
- ✓search, fetch, crawl, extract, cache, and find_similar genuinely need no API key — only research/agent-style synthesis does
- ✓every result carries a citation ID and a byte-offset source span, so an agent can quote evidence instead of paraphrasing a blob
- ✓responses are cached locally, so re-asking the same question is instant and costs nothing the second time
- ✓failure is labeled instead of swallowed — a bot-walled fetch comes back as `blocked_by_challenge`, not a challenge page disguised as content
- ✓one install wires up several coding agents at once via `--agents=claude-code,cursor,...` instead of hand-editing each MCP config
- ✓ships an 11-pack skill catalog that teaches a coding agent how to drive each tool well, managed afterward with `wigolo skills add|list|remove`
Where wigolo falls short
- △public beta — the README says it stays that way until enough people have used, kicked, and starred it to call it v1
- △research, agent, and answer-format search only produce written synthesis once you add a free LLM key (Gemini, Anthropic, OpenAI, Groq, or a local Ollama model); without one they hand back a raw brief for the agent to assemble
- △license isn't listed in the repo metadata, so check the repo directly before depending on it in a commercial product
- △self-hosting from a datacenter IP hits the same challenge-page walls a home connection wouldn't; the docs point to an opt-in proxy as the workaround
How wigolo stacks up against Firecrawl, Exa, and Tavily
Frequently asked questions
wigolo's core tools — search, fetch, crawl, extract, cache, and find_similar — run with no API key and no cloud bill, since the ranking, embeddings, and browser engine all execute on your own machine. Only research, agent, and answer-format search need an LLM key to write a synthesized, cited answer instead of a raw evidence brief.
wigolo covers the same multi-engine search, fetch, and structured-extraction ground as Tavily and Exa, but runs locally with no account and no per-query metering, caching every response so a repeat query is free. Tavily and Exa are cloud APIs you pay for by the call.
wigolo's `--agents` install flag wires up claude-code, cursor, codex, gemini-cli, opencode, vscode, windsurf, zed, and antigravity in one command. Any other MCP client, agent framework, or self-hosted agent can still register wigolo manually by pointing at `npx -y wigolo` in its own MCP config.
wigolo runs without an LLM API key for its search, fetch, crawl, extract, cache, and find_similar tools. Only research, agent, and `search format=answer` need one — without a key configured, wigolo hands back the raw evidence and a structured brief instead of a written synthesis.
wigolo is in public beta, by the README's own description — held to a 7,600-test suite and described as stable, but the project says it stays in beta until enough people have used, kicked, and starred it to call it v1.
wigolo supports macOS, Linux, and Windows for the local engine `npx wigolo init` sets up, and Node 20 or newer is required on any of them. Linux users running the headless browser get a dedicated fix too — `wigolo warmup --browser` installs the missing OS libraries automatically.
The problem it solves
Developers wiring an AI coding agent into the live web are stuck choosing between a metered API like Firecrawl, Exa, or Tavily, or a serial built-in WebSearch tool-loop that can't fan multiple queries out in parallel. wigolo runs the search, fetch, crawl, and extract stack locally instead — no API key, no metered bill — and returns evidence pinned to a byte-exact source span rather than an unstructured blob of text.
Best use cases
- •Setting up wigolo AI research workflows that hand back a cited report instead of a raw list of search links
- •Giving a self-hosted agent — an n8n flow, a custom LangChain pipeline — web access without a Firecrawl or Tavily subscription
- •Embedding local search straight into an app via wigolo-sdk instead of standing up a separate REST server
- •Watching a docs page or a competitor's pricing page for changes with diff/watch and a webhook
Who should try it — and who should skip
Worth it if you're wiring a coding agent or a self-hosted pipeline into the live web and don't want a metered search bill — setup is one `npx wigolo init` command, and the core tools need zero configuration afterward. Skip it if you need a fully mature, out-of-beta dependency today, or if a specific paid vendor's polish — Exa's rendered comparison pages, say — matters more to your use case than the cost.
Related repositories
Want a second opinion on wigolo?
Ask an AI that can read this page — one click and you get its take on wigolo.