Why Agents Use It

A single install gives your agent live search, page reading, claim verification, and citation-ready context without requiring an API key by default.

| Agent job | Command | What the agent gets | | --- | --- | --- | | Ground an answer | zero-context "FastAPI lifespan docs" | compact Markdown context with citations | | Verify a claim | zero-verify "Python 3.13 is the latest stable release" | supported / contested / likely false verdict | | Build an evidence report | zero-report "AI regulation news" | rationale, source digest, warnings, next steps | | Serve an MCP client | zero-mcp | search_web, llm_context, browse_page, verify_claim, evidence_report |

Quick start

pip install zero-api-key-web-search

# Search the web
zero-search "Python 3.13 release" --json

# Inspect provider options
zero-search providers

# Build citation-ready LLM context
zero-context "Python 3.13 stable release" --goggles docs-first

# Read a page
zero-browse "https://docs.python.org/3/whatsnew/" --json

# Verify a claim
zero-verify "Python 3.13 is the latest stable release" --deep --json

# Full evidence report
zero-report "Python 3.13 stable release" \
  --claim "Python 3.13 is the latest stable release" --deep --json

Legacy CLI aliases (search-web, browse-page, verify-claim, evidence-report) also work.

Node-based agent runtimes can use the npm wrapper once the package is published. The wrapper source is included in this repository; see docs/npm-package.md.

The 30-Second Pitch

• Zero-key default: useful immediately for local agents, evals, demos, and prototypes.
• MCP-native: works as a reusable tool server for Claude Code, Cursor, Copilot-style clients, Codex, Gemini, OpenClaw, and other MCP-compatible runtimes.
• LLM-context first: zero-context returns context a model can actually use, not just a pile of links.
• Evidence-aware: zero-verify and zero-report preserve support, conflict, source quality, freshness, and domain diversity.
• Provider-aware: start free with ddgs, add self-hosted searxng, or opt into Bright Data for production reliability and geo-targeting.

Why this over a plain search wrapper?

| Feature | Plain search | Zero-API-Key Web Search | | --- | --- | --- | | Live search results | ✅ | ✅ | | News / images / videos / books | ❌ | ✅ | | Region & time filtering | ❌ | ✅ | | Full-page text extraction | ❌ | ✅ | | Claim verification with evidence scores | ❌ | ✅ | | Supporting vs. conflicting evidence | ❌ | ✅ | | Citation-ready evidence reports | ❌ | ✅ | | Dual-provider cross-validation | ❌ | ✅ | | API key required | Often | Never by default | | Cost | Sometimes | Free by default |

Compare the Shape

| Project shape | Best at | Tradeoff | | --- | --- | --- | | Plain search wrapper | returning links quickly | leaves grounding, citation shaping, and conflict handling to the agent | | Hosted search API | managed reliability and scale | usually requires an account/key from the first request | | Zero-API-Key Web Search | local agent search infrastructure with optional production providers | default results depend on free upstreams unless you add SearXNG or Bright Data |

This project is not trying to be a hosted search engine. It is the missing search/evidence layer inside agent runtimes.

MCP server

Works with Claude Code, Cursor, Copilot, and any MCP-compatible agent:

{
  "mcpServers": {
    "zero-api-key-web-search": {
      "command": "zero-mcp"
    }
  }
}

For npm/npx-based MCP launchers after npm publication:

{
  "mcpServers": {
    "zero-api-key-web-search": {
      "command": "npx",
      "args": ["zero-api-key-web-search", "zero-mcp"]
    }
  }
}

Six tools exposed: list_providers, search_web, llm_context, browse_page, verify_claim, evidence_report.

Platform support

| Platform | Status | Entry point | | --- | --- | --- | | CLI | Ready | zero-search, zero-context, zero-browse, zero-verify, zero-report | | MCP | Ready | zero-mcp | | Claude Code | Ready | .claude/skills/zero-api-key-web-search/SKILL.md | | Gemini | Ready | GEMINI.md + .gemini/SKILL.md | | Cursor | Ready | .cursor/rules/zero-api-key-web-search.md | | Copilot | Ready | .github/copilot/instructions.md | | Codex | Ready | .codex/SKILL.md | | Continue | Ready | .continue/skills/zero-api-key-web-search/SKILL.md | | Manus | Ready | Root SKILL.md + docs/manus.md | | Kiro | Ready | .kiro/steering/zero-api-key-web-search.md | | OpenClaw | Ready | zero_api_key_web_search/skills/SKILL.md |

How verification works

zero-verify uses the evidence-aware heuristic v3 model:

1. Search for the claim across available providers
2. Score each source on keyword overlap, source quality, freshness
3. Classify as supporting, conflicting, or neutral
4. Optionally fetch top pages for deeper page-aware analysis
5. Render a verdict with confidence and evidence breakdown

| Verdict | Meaning | | --- | --- | | supported | Strong evidence, low conflict | | likely_supported | Leans positive, not decisive | | contested | Support and conflict both meaningful | | likely_false | Conflict strong, support weak | | insufficient_evidence | Too weak for any firmer verdict |

This is a heuristic evidence classifier, not a proof engine. See docs/trust-model.md for details and limitations.

Free dual-provider setup

Default install uses DuckDuckGo. For stronger cross-validated evidence, add a free self-hosted SearXNG:

./scripts/start-searxng.sh
export ZERO_SEARCH_SEARXNG_URL="http://127.0.0.1:8080"
./scripts/validate-free-path.sh

Or with Docker Compose:

cp .env.searxng.example .env
docker compose -f docker-compose.searxng.yml up -d

Full guide: docs/searxng-self-hosted.md.

Agent search controls

Provider profiles make backend choice explicit:

| Profile | Providers | Best for | | --- | --- | --- | | free | ddgs | zero-setup local use | | free-verified | ddgs, searxng | free cross-validation | | production | brightdata | production reliability and geo-targeting | | max-evidence | ddgs, searxng, brightdata | maximum provider diversity |

zero-search "FastAPI lifespan docs" --profile free-verified --goggles docs-first
zero-context "FastAPI lifespan docs" --profile free --goggles docs-first
zero-report "AI regulation news" --profile production --json

Built-in Goggles-lite presets:

| Goggles | Effect | | --- | --- | | docs-first | boosts docs, API, support, release-note, and official-looking sources | | research | boosts academic, institutional, paper, and study-oriented sources | | news-balanced | boosts reporting/analysis signals and demotes low-context aggregators |

You can also pass a JSON file to --goggles with boost_domains, block_domains, demote_domains, and boost_title_terms.

Full guide: docs/agent-search-controls.md.

More agent integration material:

• Agent Developer Guide
• Demo Transcript
• Launch Kit

Optional Bright Data provider

The default path stays free and zero-key. For production agents that need higher reliability, structured SERP data, geo-targeted results, or stronger cross-provider verification, enable the optional Bright Data provider.

export ZERO_SEARCH_BRIGHTDATA_API_KEY="..."
# Optional if your Bright Data SERP zone is not named web_search:
export ZERO_SEARCH_BRIGHTDATA_ZONE="web_search"

zero-search providers
zero-search "AI regulation news" --provider brightdata --type news --region us-en --json
zero-report "Tesla Q1 2026 deliveries" \
  --claim "Tesla deliveries increased year over year" \
  --provider ddgs --provider brightdata --deep --json

New Bright Data users can sign up here: https://get.brightdata.com/h21j9xz4uxgd.

| Provider | Best for | | --- | --- | | ddgs | zero-setup local search | | searxng | free self-hosted cross-validation | | brightdata | production-grade, geo-targeted, structured SERP evidence |

Evidence report example

{
  "verdict": "contested",
  "confidence": "MEDIUM",
  "executive_summary": "Evidence is split...",
  "verdict_rationale": ["Source A supports...", "Source B contradicts..."],
  "coverage_warnings": ["Single-provider evidence path."],
  "source_digest": [
    {"title": "...", "url": "...", "classification": "supporting", "evidence_strength": 3}
  ],
  "next_steps": ["Add a second provider for cross-validation."]
}

Architecture

zero_api_key_web_search/
  core.py              # UltimateSearcher — search, verify, report engine
  browse_page.py       # Readability-style page text extraction
  mcp_server.py        # MCP server (6 tools)
  transport.py         # SSL/TLS helpers
  search_web.py        # CLI: zero-search
  context.py           # CLI: zero-context
  browse_page.py       # CLI: zero-browse
  verify_claim.py      # CLI: zero-verify
  evidence_report.py   # CLI: zero-report
  providers/
    base.py            # SearchProvider protocol (sync + async)
    ddgs.py            # DuckDuckGo provider
    searxng.py         # SearXNG provider
    brightdata.py      # Optional Bright Data SERP provider
  skills/
    SKILL.md           # Bundled OpenClaw skill

Key engineering features:

• Circuit breaker: Trips after 3 consecutive provider failures, auto-resets after 60s
• Async support: asearch() for concurrent provider calls via asyncio.gather
• Structured logging: Configurable logging at search/verify/report entry points
• Readability heuristic: Semantic HTML5 + ARIA roles + text density scoring
• Baseline comparison: Majority-vote and keyword-count baselines in reports
• Sub-claim decomposition: Targeted sub-queries for independent evidence gathering

Installation

pip install zero-api-key-web-search

Python 3.10+ required. No API keys, no accounts, no configuration needed.

Optional npm wrapper source:

npm pack --dry-run

Development

pip install -e ".[dev]"
python -m pytest tests/ -q           # 98 tests
ruff check zero_api_key_web_search/ tests/
pyright zero_api_key_web_search/     # 0 errors
coverage report --fail-under=80       # 85% coverage

Verification for ecosystem reviewers

1. zero-report "Python 3.13 stable release" --claim "Python 3.13 is the latest stable release" --deep --json
2. docs/ecosystem-readiness.md
3. docs/gemini-submission-checklist.md
4. docs/trust-model.md

License

MIT License.