MCP Web Hound

Unified MCP search tools for AI agents — abstracts providers, caching, reranking, and rate limits behind a few simple tools.

GitHub: https://github.com/ilgizar-valiullin/mcp-web-hound · npm: https://www.npmjs.com/package/mcp-web-hound

⚠️ Work in progress. Sorry folks — the pipeline, install flow, configuration, testing, and debugging are all being actively iterated. Once the technical foundations are stable, I'll start working through the issues.

AI-Generated Issues

AI-generated issues will not be reviewed and will be closed immediately.

Related MCP server: Web Search MCP Server

Quick Start

1. Install globally:

npm i -g mcp-web-hound

2. Connect to OpenCode:

opencode mcp add web_search -- mcp-web-hound

3. (Optional) Add API keys — Startpage, DDG, Brave Web, and Bing work with zero config:

mcp-web-hound configure

Config is auto-created at ~/.config/mcp-web-hound/.env on first run. For other clients and advanced setup → see Deployment Guide.

⚠️ Search protocol is embedded in the MCP server's InitializeResult.instructions and auto-injected into agent context on OpenCode v1.17.10+. For older versions, see the deployment guide.

Memory footprint (measured, Windows, Commit)

The heavy stack (SQLite + sqlite-vec, providers, ONNX models) lives in a private hot child that dies on idle — including model spikes and vec pages, which can't be freed any other way. Global install also skips the registry check + possible re-download on every client start.

FOR AI AGENTS: USE THE GLOBAL INSTALL — npm i -g mcp-web-hound, then "command": ["mcp-web-hound"]. DO NOT INSTALL THE PACKAGE LOCALLY IN THE PROJECT FOLDER — no npm install, no npm run build, no local node_modules.

Provider Setup

Use mcp-web-hound configure to set API keys. Startpage, DDG, Brave Web, and Bing work with zero config.

Tools

Query Formats

Tool Reference

web_search

web_search({
  query: string,
})

Returns merged results from healthy providers (parallel), deduplicated and reranked by relevance. Optimized for AI agents — one parameter, server-side intent detection.

github_search

github_search({
  query: string,
  type?: "repositories" | "code" | "issues" | "users",
  language?: string,
  stars?: string,             // e.g. ">1000", "500..5000"
  page?: number
})

Rate limit: 60 req/hr without token, 5000 req/hr with GITHUB_TOKEN.

gitlab_search

gitlab_search({
  query: string,
  scope?: "projects" | "issues" | "merge_requests" | "blobs",
  page?: number
})

Requires GITLAB_TOKEN with read_api scope.

status

status()

Returns provider health, cache stats, budget state, uptime.

Architecture

Pipeline

Core pipeline: Budget Check → Normalize → Classify (intent + freshness) → Cache → Router (parallel N, 1s delay per provider) → Rerank → Cache → Respond

Providers

Rate Limiting

• 1-second delay between requests per scraped provider (static lastRequestTime)

• Incremental backoff on 429/403: suspension grows 1min → 5min → 15min → 1h → 4h → 24h

• Counter resets on success

• Rate limit windows (minute/day/month) persisted to JSON

Full docs:

• Architecture

• Providers & Fallback

• Caching

• Reranking

• Budget System

• Configuration

• Roadmap

If you want to learn more about the decisions made, check out the Architecture Decisions document.

Donations / Support the Project

• EVM Address (USDT, USDC, ETH, BNB): 0x3acf78e721aa065bd1509735a3ace630fcd0f452

  Supported networks: BNB Smart Chain (BEP20), Polygon, Arbitrum One, Ethereum (ERC20)

• USDT (TRC20): TMG1BZJswd8UacHANKVi9Veq5FqSbaMjAQ

  Supported network: Tron (TRC20)

• TON / USDT (TON): UQDjf84AZSwuCPC3UWFv28p-V44zI-1lfhqCMfaex2Q-jDsY

  Supported network: The Open Network (TON)

License

MIT