Complete Guide to wigolo: Giving AI Coding Agents Local Web Search Capabilities

What is wigolo?

If you're using AI coding agents like Claude Code, Cursor, or Codex to write code, you've probably run into a critical flaw: they can't browse the internet by default. When your agent needs to look up the latest documentation, search for an API usage pattern, or read a technical blog post, it can only rely on stale knowledge from its training data — and that's simply not enough in a fast-moving tech ecosystem.

wigolo is an open-source tool built to solve exactly this problem. It's a local-first, web-intelligent MCP server that gives any AI agent the ability to search, scrape, crawl, extract, and research the internet — with no API key required and completely free.

What can wigolo do?

wigolo provides 10 core MCP tool functions covering all the web capabilities an AI agent might need:

• search — Web search queries (no API key, runs locally)
• fetch — Grab web page content and extract the body text
• crawl — Full-site crawling across multiple pages
• extract — Structured data extraction from web pages
• cache — Local persistent cache to avoid redundant requests
• find-similar — Find pages similar to a given piece of content
• research — Autonomous research loop that synthesizes information from multiple sources (requires LLM)
• gather — Automated collection loop for topic-based information gathering
• doctor — Health check to diagnose configuration issues
• status — View runtime status and statistics

All core functions run entirely offline within the ~/.wigolo/ directory — your data never leaves your machine.

Installation & Quick Start

Requirements

• Node.js ≥ 20
• ~1.5 GB of disk space

One-Command Install

Setting up wigolo is incredibly simple — just one command:

npx wigolo init --agents=claude-code

This command automatically: 1. Downloads the browser engine and local model 2. Runs a health check 3. Writes the MCP configuration file for you

The --agents parameter supports auto-configuration for these agents: - claude-code — Claude Code - cursor — Cursor IDE - codex — ChatGPT Codex - gemini-cli — Gemini CLI - vscode — VS Code - windsurf — Windsurf IDE - zed — Zed IDE - antigravity — Antigravity

Once installed, you can check the status anytime with:

npx wigolo doctor

If everything is set up correctly, you'll see a green status report for all components.

Integration with Other Agents

If you're using an MCP client not on the auto-config list (like LangChain, CrewAI, or n8n), you can register it manually:

# Skip --agents for manual setup
npx wigolo init

Then add this to your MCP configuration file:

{
  "mcpServers": {
    "wigolo": {
      "command": "npx",
      "args": ["-y", "wigolo", "stdio"]
    }
  }
}

Complete Uninstall

If you don't need it anymore, clean everything up in one go:

npx wigolo config --uninstall --yes

Advanced Usage

Enable LLM-Powered Research

wigolo's search and scraping core features work without any API key. But if you want to unlock the more powerful research and gather features (which need an LLM to synthesize information across multiple sources), all you need is a free Gemini API key:

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY="your-free-key"

You can grab a free key at Google AI Studio. The free tier is more than sufficient.

Other supported LLM providers include: - anthropic — Claude API - openai — OpenAI API - groq — Groq API - ollama — Local Ollama (fully offline)

Running as a REST API Service

If you want remote agents (like an n8n automation running on a VPS) to use wigolo too, you can start it in serve mode:

npx wigolo serve --port 3000

Then call it with curl:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"latest Rust async best practices"}}}'

Real-World Workflow with Claude Code

wigolo works best when paired with Claude Code. Here's a real workflow:

Scenario: Looking up the latest usage of a new library

You tell Claude Code:

Use wigolo to search for "Rust tokio 2026 best practices" and summarize the latest approaches for me

Claude Code will automatically invoke wigolo's search tool to pull in results, then synthesize information from multiple pages into an accurate, up-to-date summary.

Comparison with Similar Tools

wigolo's biggest advantage is being local-first — all your search history, cached data, and research results are stored under ~/.wigolo/ and never uploaded to any cloud service.

Self-Hosting

For team use cases, you can deploy wigolo on a VPS so multiple developers' agents can share the same search instance.

Docker Deployment

FROM node:20-slim
RUN npm install -g wigolo
EXPOSE 3000
CMD ["npx", "wigolo", "serve", "--port", "3000"]

Nginx Reverse Proxy

server {
    listen 443 ssl;
    server_name wigolo.yourdomain.com;

    location /mcp {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
    }
}

FAQ

Is wigolo safe? Does it leak my data?

No. wigolo is a local-first tool — all data is stored in the ~/.wigolo/ directory. It does not send your search history or cached data to any external server. See the privacy & security docs for details.

My agent's wigolo calls are too slow — what can I do?

Run npx wigolo doctor for diagnostics. If the local model hasn't finished downloading, the first search will be slower. Once a search completes, the results are cached, and subsequent queries will be significantly faster.

Which search engines does wigolo support?

wigolo has multiple built-in search engines and scraping capabilities, with no external API required. You can also add custom search engines and content extractors through the plugin system.

Summary

wigolo is the most mature open-source local web-intelligent MCP server available today, filling the critical gap of "AI coding agents can't go online." Its core value propositions:

1. Zero cost — Core features are completely free, no API key needed
2. Privacy-first — All data stored locally
3. Ready out of the box — One command to install and integrate with agents
4. Full-featured — Search, scraping, crawling, research, and caching all covered
5. Highly extensible — Plugins, SDK, REST API, and Docker deployment supported

If your AI coding workflow is still missing that "web search" piece, wigolo is the best choice available right now.

📌 Related Links - wigolo GitHub - wigolo Docs - wigolo on MCP Market