Provides AI agents with local-first web intelligence including search, crawling, extraction, and autonomous research capabilities.
Also known as KnockOutEZ/wigolo
- Stars
- 5,544
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 0.2.1
- Last commit
- Nov 14, 2026
- License
- —
What is wigolo MCP?
wigolo provides AI agents with local-first web intelligence including search, crawling, extraction, and autonomous research capabilities. It exposes 10 tools, such as fetch, search, crawl.
Summary generated from the project's README
About wigolo MCP server
wigolo provides a local-first web intelligence layer designed specifically for AI agents. It enables tools like Claude Code, Cursor, and Windsurf to perform complex web tasks including searching, crawling, and data extraction without requiring external API keys or incurring metered costs. The system runs locally on macOS, Linux, or Windows, storing all cache, embeddings, and configurations within the ~/.wigolo/ directory to ensure privacy.
Developers can deploy this as an MCP server, a REST endpoint, or via an SDK. While core tools like search, fetch, and extract are entirely keyless, the research and agent tools can be enhanced by connecting a Gemini, Anthropic, or OpenAI key. Users can also maintain a fully local setup by using Ollama as the LLM provider. The server is built to handle anti-bot challenges through a tiered router and provides transparent telemetry, such as flagging blocked pages or stale cache, so agents can make informed decisions based on the quality of the data.
What you can do with it
- 1Autonomous web researchAn AI agent can decompose a complex question into sub-queries and synthesize a cited report using the research tool.
- 2Structured data extractionA developer can instruct an agent to pull specific information like tables or JSON-LD from a webpage.
- 3Automated web monitoringYou can set up a system to detect and report specific changes made to a webpage over time.
- 4Parallel multi-engine searchingAn agent can execute multiple search queries across different engines simultaneously to gather broad information.
Written from the project's README. Every use case is checked against a quote from it.
How to install wigolo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall wigolo MCP in Claude Code
$ claude mcp add --env 'YOUR_API_KEY=<YOUR_YOUR_API_KEY>' wigolo -- npx -y wigoloInstall wigolo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"wigolo": {
"command": "npx",
"args": [
"-y",
"wigolo"
],
"env": {
"YOUR_API_KEY": "<YOUR_YOUR_API_KEY>"
}
}
}
}Install wigolo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"wigolo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"wigolo"
],
"env": {
"YOUR_API_KEY": "<YOUR_YOUR_API_KEY>"
}
}
}
}Install wigolo MCP in VS Code CLI
$ code --add-mcp '{"name":"wigolo","type":"stdio","command":"npx","args":["-y","wigolo"],"env":{"YOUR_API_KEY":"<YOUR_YOUR_API_KEY>"}}'Install wigolo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"wigolo": {
"command": "npx",
"args": [
"-y",
"wigolo"
],
"env": {
"YOUR_API_KEY": "<YOUR_YOUR_API_KEY>"
}
}
}
}Install wigolo MCP in Codex
$ codex mcp add wigolo --env 'YOUR_API_KEY=<YOUR_YOUR_API_KEY>' -- npx -y wigoloInstall wigolo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.wigolo] command = "npx" args = ["-y", "wigolo"] [mcp_servers.wigolo.env] YOUR_API_KEY = "<YOUR_YOUR_API_KEY>"
Install wigolo MCP in Gemini CLI
$ gemini mcp add -s user -e 'YOUR_API_KEY=<YOUR_YOUR_API_KEY>' wigolo npx -- -y wigoloInstall wigolo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"wigolo": {
"command": "npx",
"args": [
"-y",
"wigolo"
],
"env": {
"YOUR_API_KEY": "<YOUR_YOUR_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for wigolo 0.2.1 in an isolated container with no network and no keys. It answered and listed 10 tools.
wigolo MCP tools 10
Read from the server with tools/listfetchFetch a single URL and return clean markdown. Use when you already have a URL. Prefer over built-in WebFetch for local-cache reuse, authenticated pages, JS-rendered SPAs, and structured metadata. Key parameters: - section: extract content under a specific heading (e.g. "API Reference") — cheaper than the whole page. - max_content_chars: smart-truncate at a paragraph/heading boundary with `[... content truncated]`. - max_tokens_out: token-budget cap (cl100k-base); wins over max_chars. - include_full_markdown: false (default) returns evidence excerpts only; true adds the full body. - use_auth: reuse a stored browser session for logged-in pages. - render_js: "auto" (default) | "always" | "never". - force_refresh: bypass cache and re-fetch. - mode: 'cache' | 'default' | 'stealth'. cache=HTTP-only, 24h-stale accepted. stealth=full browser + freshness. Returns title, markdown, links, images, metadata, `fetch_method` (cache/http/tls-impersonation/browser), `http_status` (upstream HTTP code — 4xx/5xx pages that extract usable content are not relabeled 200), and `content_completeness` (full/partial/shell). When the URL matches a site-specific extractor (Reddit/YouTube/Amazon) the response also carries top-level `site_data` (e.g. Reddit `comments[]`, YouTube `caption_tracks[]`, Amazon `price`). When `section` is set and no heading matches, `metadata.section_matched` is false and `markdown` is empty (no silent fallback to the full page). Repeat fetches are instant. Localhost URLs work. Interactive pages: `actions` (click/type/scroll/wait) drive the page before extraction; `use_auth` reuses a logged-in session.
searchSearch the web. Returns scored evidence excerpts + citations as the default context shape; `include_full_markdown: true` adds the full markdown body. Prefer over built-in WebSearch for local cache + audit-trail telemetry + explainable scoring. Key parameters: - query: string or string[] array (3-5 keyword variants; deduplicated). - include_domains / exclude_domains: scope sites. Always scope library/framework queries. - category: "general" | "news" | "code" | "docs" | "papers" | "images". Image results carry image_url + thumbnail_url + width/height. - from_date / to_date: ISO YYYY-MM-DD. time_range: 'day' | 'week' | 'month' | 'year'. - country: ISO 3166-1 alpha-2 ("us", "gb") — geographic boost. - exact_match: quoted-phrase search. - max_results: 5 default. - format: omit = evidence context. 'answer' | 'stream_answer' = sampling synthesis (falls back to evidence). - search_depth: 'ultra-fast' (cache-only ≤300ms) | 'fast' | 'balanced' (default) | 'deep'. - include_images / include_favicon: opt-in images[] + per-result favicon. - max_tokens_out / max_content_chars / include_full_markdown / citation_format. - force_refresh + mode ('cache' | 'default' | 'stealth'). Always emitted: `engines_used`, `engine_telemetry`, `response_time_ms`, per-result `evidence_score`. Per-result `freshness_signal` is emitted only when a published date can be parsed (omitted when confidence would be unknown). Brand-domain top-3 collision → `brand_collision_warning` with rewrites. `query_understanding` exposes intent/entities. Quote [N] or {citation_id}.
crawlCrawl a site from a seed URL and return content from many pages. Use for indexing docs, wikis, multi-page references. Built for offline reuse: every page lands in the local cache. Key parameters: - strategy: "bfs" (default) | "dfs" | "sitemap" (fastest for doc sites) | "map" (URL-only discovery). - max_depth: link-following depth (default 2). - max_pages: page cap (default 20). - include_patterns / exclude_patterns: regex filters on URLs. - max_tokens_out / include_full_markdown / citation_format: budget + shape controls. Returns pages[] with title, evidence, depth, and `content_completeness` (per page — full/partial/shell, so you can skip un-rendered shell pages). Content is deduplicated across pages (anchor-fragment aware). All pages are cached for later `cache` / `find_similar` queries.
cacheSearch previously fetched content without hitting the network. Run this BEFORE any search/fetch — cache hits return instantly with full markdown. Key parameters: - query: FTS5 full-text search over cached markdown + titles (supports AND, OR, NOT, "phrase"). - url_pattern: glob filter on URLs (e.g. "*example.com*"). - since: ISO date — only entries cached after this date. - stats: true to get cache size, entry count, oldest/newest dates. - clear: true to delete matching entries. Persists across sessions. No remote round-trip.
extractExtract structured data from a URL or raw HTML. Use for specific data points (tables, prices, schema fields) rather than whole-page markdown. Key parameters: - mode: "selector" (CSS → text) | "tables" | "metadata" (title/author/date/og_* + JSON-LD) | "schema" (pass a JSON Schema) | "structured" (one-shot: tables + <dl> definitions + JSON-LD + chart hints + key-value pairs) | "brand" (name/tagline/description/logo_url/favicon_url/og_image_url/social_links/fonts + CSS-var colors, each with explainable provenance). - css_selector: required for mode="selector". - schema: required for mode="schema". - multiple: return all matches (mode="selector" only). Prefer mode="structured" over chaining multiple extract calls — one response carries `{ tables, definitions, jsonld, chart_hints, key_value_pairs }`. chart_hints surfaces SVG titles, aria-labels, figcaptions for charts whose data is JS-rendered. Metadata parity with `fetch` (same og_/canonical_url shape). `mode: "brand"` walks JSON-LD Organization/Brand/WebSite → OG/Twitter Card meta → `<link rel=icon>` → CSS custom properties → heuristic header/footer DOM; `provenance` records the winning source. Provenance enums: logo ∈ {json-ld, og:logo, link[rel=icon], heuristic, unknown}; colors ∈ {css-vars, palette-extraction, unknown}; fonts ∈ {css-vars, css-rule, inline-style, google-fonts-link, unknown}. Honesty: `name` and `logo_url` are unset when no explicit source emits them — favicons never promote to `logo_url`. `mode: "schema"` is evidence-only: LLM-sourced fields not present in source text are returned as `null` with a warning.
find_similarFind content related to a URL or concept. Best after a successful crawl/fetch — the local cache makes recommendations cheap. Concept-only queries on a cold cache often return 0-2 weak matches; warm the cache first via `crawl` / `fetch` for materially better results. Key parameters: - url: known-good page; its content + embeddings drive similarity. - concept: free-text alternative to url. Thin cache → expect `cold_start` to fire. - max_results: default 5. - include_cached: true (default) to search cache first; false = web only. - threshold: minimum fused score (0-1, default 0.5). - include_ranking_debug: opt-in per-result `ranking_debug` { fts5_rank, embedding_rank, web_rank, rrf_score } so you can audit which signal won. - max_tokens_out / include_full_markdown / citation_format: budget + shape controls. Pass either url or concept. Three signals fused via RRF: keyword (FTS5), embeddings, optional live web. Each result carries `match_signals` with `embedding_rank`, `fts5_rank`, `fused_score`. When local signals are weak (cache empty, no hits, or concept mode returns only 1-2 cache matches), the response carries `cold_start` — pass it verbatim to the user (tune `WIGOLO_FIND_SIMILAR_COLD_START_THRESHOLD` to adjust). Returns results[], method ("hybrid" | "embedding" | "fts5" | "search"), cache_hits, search_hits, embedding_available, total_time_ms.
researchMulti-step research on a complex question. Decomposes into sub-queries, searches in parallel, fetches sources, synthesizes a cited report. Beats chaining `search` + `fetch` manually for multi-source synthesis. LLM-optional: with a synthesis LLM configured, the returned `report` is a written answer. Without one it returns a structured, cited `brief` (key_findings/highlights/sections) — YOU write the final answer from it; do not hand the user the raw structure as a weak result. For the best research quality a free Gemini API key (or any provider) is strongly recommended. Key parameters: - question: the research question. - depth: 'quick' (~15s, 2 sub-queries) | 'standard' (~40s, 4 sub-queries, default) | 'comprehensive' (~80s, 7 sub-queries). - max_sources: override per-depth source count. - include_domains / exclude_domains: scope. - schema: optional JSON Schema — structures the report. - stream: progress notifications per phase. - max_tokens_out / include_full_markdown / citation_format: budget + shape controls. Returns report (markdown with [N]), citations[], sources[], sub_queries[], depth, total_time_ms, sampling_supported, and `brief` with `topics`, `highlights`, `key_findings`, `sections` (overview.cross_references, comparison, gaps — gaps lists any named sub-entity research could not corroborate).
agentNatural-language data gathering across sources. Plans queries + URLs from a prompt, executes in parallel, optionally extracts structured fields, synthesizes. Full step transparency. LLM-optional: with a synthesis LLM configured it writes the summary; without one it returns gathered evidence + a step log (plus schema-shaped fields when a schema is given) — YOU write the summary from the returned evidence, never present the raw step log as a poor result. For best agent results configure a free LLM key (e.g. Gemini). Key parameters: - prompt: NL description of what to gather (e.g. "pricing for the top 5 CRM tools"). - urls: optional seed URLs. - schema: optional JSON Schema — extracts matching fields from each page and merges. - max_pages: default 10. - max_time_ms: default 60000. - stream: progress notifications per step. - max_tokens_out / include_full_markdown / citation_format: budget + shape controls. Pipeline: plan → search+fetch in parallel within budget → optional schema extraction → synthesize. `steps[]` exposes every action with timing. Uses MCP sampling when supported; falls back to keyword extraction otherwise. Returns result, sources[], pages_fetched, steps[], total_time_ms, sampling_supported.
diffCompute a diff between two markdown bodies or two URL fetches. Key parameters: - old: { url?, markdown?, content_hash? } — left-hand side. URL form reads from cache; cache miss returns a structured `cache_miss` error (no network re-fetch). - new: { url?, markdown? } — right-hand side. Same cache rules as `old`. - output: 'unified' (default, git-style patch) | 'hunks' (structured array) | 'summary' (line counts only). - granularity: 'line' (default) | 'word' | 'section'. Section walks H1/H2/H3 boundaries and tags each hunk with `section_title`. Returns `{ changed, summary, unified_diff?|hunks?, truncated? }`. `summary` always present (added/removed/modified lines + total_changed_chars). Above the 5000-line cap the engine emits `truncated: true` plus an approximate summary — never silently degrades.
watchSchedule lazy re-checks of a URL and surface diffs on change. Persistent across sessions — jobs survive MCP server restarts. LAZY EXECUTION — NOT CRON. There is no background daemon. Checks fire ONLY when: 1. You explicitly call `watch({ action: 'check', job_id })`, OR 2. Any OTHER wigolo tool runs and the job's interval has elapsed (overdue jobs are triggered fire-and-forget in the background). A job on an idle MCP server will not fire until the next tool call. Do not expect cron-like accuracy. Key parameters: - action: 'create' | 'list' | 'check' | 'pause' | 'resume' | 'delete'. - url (create-only): must be a public http/https URL. Loopback, RFC 1918 ranges, link-local, and non-http(s) schemes are rejected at registration. - interval_seconds (create-only): minimum 60 — sub-minute polling is refused to respect target-site rate limits. - selector (create-only, optional): CSS selector for future selector-scoped diffs. Persisted now for forward compatibility; the diff is currently full-page. - notification (create-only, optional): 'inline' (default — change reports come back on the next `action: 'check'`) or a public webhook URL. Same SSRF guard as `url`. Webhook delivery is best-effort POST — no retry / no queue / no backoff. - job_id (check/pause/resume/delete). `list` returns each job's `staleness_seconds` so you can see how overdue each check is: negative = not yet due, positive = overdue by N seconds. Pair with `action: 'check'` to force one immediately. Idempotent `create`: identical url + interval + selector returns the existing `job_id` — does not duplicate the row.
Configuration
YOUR_API_KEYRequiredSecretYour API key for the service
GEMINI_API_KEYWIGOLO_EAGER_WARMUPWIGOLO_GITHUB_TOKENWIGOLO_LLM_PROVIDERWIGOLO_SEARCHWIGOLO_TLS_TIER
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableknockoutez/wigolo is public and reachablegithub.com/knockoutez/wigolo ↗Pass
- Package names this repository as its sourcewigolo names knockoutez/wigolo as sourcenpmjs.com/package/wigolo ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for wigolonpmjs.com/package/wigolo/v/0.2.1#provenance ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-14github.com/knockoutez/wigolo ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from wigoloPass
- No critical advisory in the package or its dependencies400 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubLocal-first web intelligence for AI agents — no keys, no cloud, no metered bill.
works with Claude Code · Cursor · Codex · Gemini CLI · OpenCode · VS Code · Windsurf · Zed · Antigravity and beyond LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n & self-hosted agents · any MCP client · plain REST
sponsored by
Quickstart · Tools · Why wigolo · Discord · Sponsors · Benchmark · Docs · Examples · Licensing · Feedback · FAQ
Join the community on Discord — questions, help, and what's being built next.
New features and updates ship steadily. Follow @yourtowhid on X for all of it and new ways to use wigolo, and reach out there for collaborations or feedback · also on LinkedIn
wigolo gives an AI agent one surface for everything web-related: search, fetch, crawl, extract, cache, find-similar, research, and autonomous gather loops. It runs wherever your agent runs — as an MCP server next to your coding agent, as a REST/MCP endpoint on the box where your self-hosted agents live, or embedded through an SDK inside your own app. The core tools need no API keys, nothing it touches leaves ~/.wigolo/, and no bill grows with how much your agent thinks.
Quickstart
npx wigolo init # set up the local engine — any system
npx wigolo init --agents=claude-code,cursor # …or set up + wire your day-to-day agents in one command
Requires Node ≥ 20 and ~1.5 GB of free disk on macOS, Linux, or Windows. Bare init sets up the local engine: it downloads the browser engine and on-device models, runs a health check, and reports each component. Adding --agents wires the named agents in the same run, so a coding agent you use daily is ready in one command.
- Supported agents —
--agentstakes any ofclaude-code·cursor·codex·gemini-cli·opencode·vscode·windsurf·zed·antigravity(comma-separated); wigolo writes the MCP config and, where supported, instructions for each. - Any other setup — any MCP client, agent framework, or self-hosted agent registers
npx -y wigoloin its own MCP config. The installation guide has the exact config block for every client, plus Docker, Homebrew, and single-file-binary channels. - More on the way — the supported list keeps growing, and a PR to add your agent is welcome; see CONTRIBUTING.md.
- Interactive setup —
--interactiveis a plain-text flow;--wizardis the full terminal TUI. - Defer downloads —
--no-warmupwaits until first use. A failed component download never fails setup; init reports what's not ready with the exact fix and still completes.
init is unattended by default, so it's safe in scripts and CI, and any setup problem surfaces right here in the per-component report, before your agent's first call. Search, fetch, crawl, extract, cache, and find-similar work with no API key. Check it's healthy anytime:
npx wigolo doctor
To remove everything cleanly, run npx wigolo config --uninstall --yes. You can also paste the installation guide into any AI assistant and let it do the setup; it's written to be self-contained.
Recommended — a free key for research & agent
Search, fetch, crawl, extract, cache, and find-similar are fully keyless. research, agent, and search format=answer use an LLM to write the synthesized, cited answer. Without one they hand back a raw brief and evidence for your agent to assemble. A free Gemini key turns that into a finished answer:
export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<free-key> # grab one at aistudio.google.com/apikey — the free tier is plenty
Any provider works (anthropic · openai · groq), or stay fully local and keyless with WIGOLO_LLM_PROVIDER=ollama (or any OpenAI-compatible URL). Set it in your shell or your agent's MCP env block. Providers, models, and the keyless local-model ladder are in the configuration guide.
What your agent gets back
Every search result is evidence the agent can act on. It carries a verbatim excerpt pinned to its exact position in the source, a citation ID the agent can quote, and a score it can inspect (abridged real shape):
{
"results": [{
"title": "Logical replication - PostgreSQL docs",
"url": "https://www.postgresql.org/docs/current/logical-replication.html",
"excerpt": "Logical replication is a method of replicating data objects…",
"citation_id": "src-1",
"source_span": { "start": 1042, "end": 1305 }, // byte-exact provenance
"evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 }
}],
"citations": [{ "id": "src-1", "url": "…" }],
"freshness_signal": { "published": "2026-05-12", "confidence": "high" }
}
Weak results get flagged as junk by wigolo's own scorer. Failed engines are reported and stale cache is labeled, so the agent always knows what it's standing on. Full response contracts per tool are in the tools reference.
Tools
| Tool | What it does |
|---|---|
🔎 search |
Multi-engine web search (18 direct adapters) with rank fusion, ML reranking, and an explainable per-result score. Pass a query array for parallel breadth. Scope by domain and time range, match an exact phrase, or return image results. |
📄 fetch |
Load one URL through a tiered router that auto-escalates from plain HTTP to a headless browser engine on anti-bot challenges or SPA shells. Clean markdown + metadata + links. Handles PDFs, a single-heading section, authenticated sessions, and page actions (click / type / scroll / screenshot). |
🕸️ crawl |
Multi-page crawl — BFS, DFS, sitemap, or map-only. Per-domain rate limits, robots.txt respect, boilerplate dedup. |
🧩 extract |
Structured data from a page: tables, metadata, JSON-LD, brand identity, named schemas (Article / Recipe / Product / …), or any custom JSON Schema. |
💾 cache |
Query everything already seen — keyword or hybrid semantic. Plus stats, clear, and change detection. |
🧲 find_similar |
Pages similar to a URL or a concept, via 3-way fusion of keyword + semantic + live web. |
🧠 research |
Decompose a question → fan out sub-queries → fetch sources → synthesize a cited report (or a structured brief the host LLM writes from). |
🤖 agent |
Autonomous gather loop: plan → search → fetch → extract → synthesize, with a step log, time budget, and optional output schema. |
🔁 diff + ⏱️ watch |
See exactly what changed on a page since last visit; re-check on demand and deliver changes to a webhook. |
Every tool also runs from the terminal (wigolo search "…" --json), from an interactive shell with NDJSON piping (wigolo shell), over REST, and through the SDKs — CLI reference. Per-tool guides with the full parameter set are in docs/tools.md; runnable examples are in examples/.
Why it's different
wigolo isn't a free stand-in for the paid tools — it's built to match them. It's a focused web layer for your agents: an MCP and REST surface they call directly, with the search and extraction quality the paid services charge for. What separates it:
- Built for agents. One MCP call fans out many queries across many engines in parallel, which a serial host tool-loop can't replicate. Every result carries transparent per-result scoring, and output is budget-aware.
- Honest output. Stale cache, failed fetches, degraded backends, and truncation are surfaced in the result. When a bot-protected page can't be read, you get a labeled
blocked_by_challengefailure, not a challenge shell returned as content. - $0 per query, free to re-query. Default search talks to public engines through direct adapters; the reranker and embeddings run on-device. Every response is cached, so asking again is instant and costs nothing.
- Private by default. Cache, embeddings, models, and config live under
~/.wigolo/. Nothing reaches a third party unless you explicitly opt into an LLM for synthesis.
Here's what one real result looks like, dissected. It includes the failed engine and the weak result, because those are part of the answer too:
Benchmark
All four tools converged on the same core answer, and only one of them handed back verbatim, byte-pinned evidence while doing it.
One cold query ran live inside a single Claude Fable 5 session, fanned out to four web tools on equal footing (built-in WebSearch, wigolo, Tavily, Exa), and was judged by the agent on the evidence alone. All four converged on the same answer and the same top source, so the parity is demonstrated on-screen. wigolo alone returned verbatim excerpts pinned to byte-offset source spans, an explainable score decomposition, and live per-engine telemetry, and its own scorer flagged two weak results as junk. The cloud tools earn their place too: Exa rendered the official docs' comparison matrix in full. Run your own query and you'll see the same shape.
How it compares
| wigolo | Firecrawl | Exa | Tavily | |
|---|---|---|---|---|
| Multi-engine web search | ✅ | ✅ | ✅ | ✅ |
| Fetch & structured extraction | ✅ | ✅ | ✅ | ✅ |
| Whole-site crawl & map | ✅ | ✅ | — | ✅ |
| Verbatim excerpts pinned to byte-offset source spans | ✅ | — | — | — |
| Explainable per-result score decomposition | ✅ | — | — | — |
| Persistent local memory — re-query instantly, offline | ✅ | — | — | — |
| Query data stays on your machine | ✅ | — | — | — |
| API key / account | none | required | required | required |
| Cost per query | $0 | metered | metered | metered |
Feature standing as of July 2026 — check each vendor's docs for current state.
That last row compounds, because agents ask in bursts:
Beyond your editor
The same ten tools serve every kind of agent, over whichever surface fits: MCP for coding agents, REST for everything else, SDKs to embed, and framework wrappers to drop in.
REST API — wigolo serve
One process exposes a plain-JSON REST API next to the MCP transport. No MCP client needed, just curl:
wigolo serve # 127.0.0.1:3333 — loopback is open; off-loopback requires a token
curl -sX POST http://127.0.0.1:3333/v1/search \
-H 'Content-Type: application/json' \
-d '{"query":"local-first software","max_results":5}'
POST /v1/{tool} covers all ten tools, GET /openapi.json is the OpenAPI 3.1 contract, and /mcp + /sse serve remote MCP clients from the same port. Bind past loopback and a bearer token is required, so the server fails closed by default. Point n8n, a Hermes-style assistant, or any self-hosted agent at it. → REST API
SDKs — TypeScript & Python
Thin, typed clients with an embedded local mode that finds or starts the daemon for you. No separate serve step.
TypeScript — npm install wigolo-sdk (zero-dep; Node / Bun / Deno / edge):
import { createLocalClient } from 'wigolo-sdk/local';
const { client, close } = await createLocalClient(); // reuse a running daemon, or spawn one
const res = await client.search({ query: 'local-first web search', max_results: 5 });
console.log(res.results.map((r) => r.title));
await close(); // stops the daemon only if this call spawned it
Python — pip install wigolo (standard library only; sync + async):
from wigolo import local_client
with local_client() as client: # reuse a healthy daemon, or spawn one
res = client.search(query="local-first web search", max_results=5)
for r in res["results"]:
print(r["title"], r["url"])
Framework integrations
Drop wigolo's tools into the framework you already use. You get the full ten-tool surface, including the cache / find_similar / research / agent that most framework web-tools don't ship:
| Framework | Package | What you get |
|---|---|---|
| LangChain | wigolo-langchain |
each tool as a BaseTool, plus a BaseRetriever over search / find_similar for RAG |
| CrewAI | wigolo-crewai |
wigolo_tools() → hand the set to any crew |
| LlamaIndex | wigolo-llamaindex |
a BaseReader that loads fetched / crawled / searched pages as documents |
| Vercel AI SDK | wigolo-vercel-ai-sdk |
tool factories for generateText / streamText, edge-friendly |
Docker
# stdio MCP — wire it into any MCP client as command: docker
docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo
# HTTP server for remote / multi-client use
docker run -p 3333:3333 -v wigolo-data:/data \
-e WIGOLO_API_TOKEN=a-long-random-secret \
ghcr.io/knockoutez/wigolo serve --host 0.0.0.0
The slim image lazy-loads models into the volume; ghcr.io/knockoutez/wigolo:latest-full preinstalls the browser engine. Versioned releases use the same -full suffix (for example, 0.3.1-full). Also on Docker Hub as towhid69420/wigolo. → installation & all channels
Agent skills
An 11-pack skill catalog teaches your coding agent to drive each tool well. It's installed by init and managed with wigolo skills add|list|remove. → skills
One note for self-hosters: some challenge-protected sites score IP reputation, so a datacenter IP won't clear walls a home connection would. wigolo labels those failures, and the self-hosting guide covers the opt-in proxy answer.
Star history
Refreshed daily from the GitHub API. Add a ⭐ if wigolo is useful to you.
Architecture
A single Node process speaks MCP (JSON-RPC over stdio). Everything heavy is local and lazy-loaded, so a zero-key install pays nothing for the parts it isn't using.
flowchart TD
A["🤖 AI agent<br/>any MCP client · REST · SDK"]
A -->|MCP over stdio| B["<b>wigolo</b><br/>10 tools · dynamic instructions<br/>in-process browser pool + cache + models"]
B --> C{"Tool layer"}
C --> T1["search · fetch · crawl · extract"]
C --> T2["cache · find_similar · research · agent"]
T1 --> F["⚙️ Fetch router<br/>tiered escalation, learned per domain"]
T1 --> S["⚙️ Search<br/>18 engines → rank fusion → ML rerank<br/><i>explainable evidence score</i>"]
T2 --> DB[("🗄️ Local cache<br/>keyword + vector index")]
T2 --> ML["🧠 On-device ML<br/>embeddings + reranker"]
F -.->|optional| LLM["☁️ LLM<br/>synthesis only · opt-in"]
S -.->|optional| SX["🔀 Aggregator backend<br/>opt-in legacy / hybrid"]
F --> WEB["🌍 Public web"]
S --> WEB
style B fill:#7c3aed,stroke:#5b21b6,color:#fff
style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff
style DB fill:#1e293b,stroke:#334155,color:#fff
style LLM stroke-dasharray: 5 5
style SX stroke-dasharray: 5 5
- Code beats model. Deterministic work stays off the LLM: canonicalization, rank fusion, dedup, and schema matching. The model is reserved for judgment, opt-in, and capped per request. LLM-filled fields are checked against the source and nulled if absent.
- Signal-driven routing. The fetch ladder escalates to a real browser on observable signals, not domain guesses: SPA markers, challenge bodies, thin content. It learns per domain, unlearns when a site stops needing it, and
wigolo tune listshows you exactly what it learned. - Reads pages the way a browser does. Tiered fetching waits out interstitial challenges and reuses clearances per domain, politely: robots.txt respected, per-domain rate limits, research-grade volumes. When a wall stays up, the failure is labeled and reported.
Configuration
A clean install works out of the box. Three settings raise output quality:
# 1. Synthesis — the biggest lever (research / agent / search-answer write real prose)
export WIGOLO_LLM_PROVIDER=gemini # or anthropic / openai / groq / ollama (keyless)
export GEMINI_API_KEY=<your-key>
# 2. Wider retrieval funnel
export WIGOLO_SEARCH=hybrid # core engines + aggregator fallback
export WIGOLO_GITHUB_TOKEN=... # GitHub code search 10 → 30 req/min
# 3. Land more fetches, stay warm
export WIGOLO_TLS_TIER=auto # per-domain learned fetch hardening
export WIGOLO_EAGER_WARMUP=1 # pay the ~1s model load up front
Per-call habits that pay off: query arrays (["a","b","c"]) for parallel breadth · search_depth: "deep" for queries that matter · include_domains as a hard filter for docs lookups. The full reference covers every environment variable, config-file key, search backend, cache TTL, and serve limit; it's in the configuration guide.
Docs & examples
docs/ — the complete manual: getting started · installation & channels · configuration · tools reference · CLI & shell · REST API · SDKs & integrations · self-hosting · agent skills · plugins · troubleshooting & FAQ · privacy & security
examples/ — runnable, each with a README (and most with a terminal recording): one-shot CLI, NDJSON shell pipelines, REST via curl, TypeScript & Python SDKs, Vercel AI SDK tools, pointing self-hosted n8n at a remote wigolo, watch-with-webhook, and writing your own search-engine plugin. The docs are also rendered on the site at wigolo.app/docs.
Beta & feedback
wigolo is in public beta. Everything documented here works and is held to a 7,600-test suite; it's stable, and beta is about the polish bar. It stays beta until enough people have used it, kicked it, and starred it that calling it v1 means something. Your feedback shapes what comes next, and every report is read, usually the same day:
- 🐛 Report a bug — broke, misbehaved, surprised you
- 💡 Request a feature — something it should do
- 💬 Ask anything — questions, setups, show & tell
If wigolo earns a place in your setup, three things keep it going: a ⭐ star (it's how open source gets found), a ☕ coffee (the open-source version is the full product; commercial licenses fund it, not gated features), or an email that goes straight to the one developer who wrote the code.
wigolo MCP questions
How do I add wigolo MCP to Claude Code?
Run claude mcp add --env 'YOUR_API_KEY=<YOUR_YOUR_API_KEY>' wigolo -- npx -y wigolo in your terminal. Add --scope user to make it available in every project.
How do I add wigolo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does wigolo MCP provide?
It exposes 10 tools, including fetch, search, crawl, cache, extract.
Does wigolo require API keys for web search?
No, the core tools like search, fetch, crawl, extract, cache, and find-similar are fully keyless.
What are the system requirements for wigolo?
It requires Node.js version 20 or higher and approximately 1.5 GB of free disk space on macOS, Linux, or Windows.