Your AI research assistant that cites real sources and stays honest
web-researcher-mcp is a Model Context Protocol (MCP) server that functions as an AI research assistant. Its stated purpose is to search the web (or trusted sites), analyze full sources rather than snippets, and provide citations that are intended to be reliable and verifiable.
🛠️ Key Features
Web search across the entire web
Optional narrowing to trusted sites (e.g., medical journals, court databases, news outlets, academic papers)
Source-based analysis of full content (not only snippets)
Citation and bibliography orientation (“citations you can trust”)
🚀 Use Cases
Conducting web research with cited references
Fact-checking and citation verification against real sources
Research workflows that require transparency about sources
⚡ Developer Benefits
Supports MCP-based integration for AI agents
Emphasizes anti-hallucination via citation verification and fact-checking themes
Aligned with bibliography and research-oriented tasks
⚠️ Limitations
The provided excerpt does not specify implementation constraints, supported data sources in detail, or any tool behavior beyond the cited goals.
Your AI research assistant that cites real sources and stays honest.
Search the entire web or narrow it down to just the sites you trust; medical journals, court databases, news outlets, academic papers. Analyze the full source, not just snippets. Links that work, citations you can trust, no made up closed garden pre-synthesized results.
⭐ If you're tired of AI making things up, and web-researcher-mcp helps you, give us a star ⭐ — it helps more teams discover the project.
# One-time: install uv (skip if you already have it)
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux (Windows: winget install astral-sh.uv)
claude mcp add --scope user web-researcher -- uvx web-researcher-mcp
uv fetches the right prebuilt binary for your platform and runs it — no Go, no compile, no manual PATH. Point any MCP client at uvx web-researcher-mcp. Also works with uv tool install web-researcher-mcp or pip install web-researcher-mcp.
Python SDK
python
from web_researcher_mcp import WebResearcherClient
asyncwith WebResearcherClient() as client:
response = await client.web_search("CRISPR off-target effects 2024", num_results=5)
for r in response.results:
verified = await client.verify_citation(r.url)
print(r.title, "—", "✓"if verified.exists else"?")
No dev tools needed — every method ships the same signed binary (the PyPI wheels vendor it; the others download it and verify its checksum) and puts it on your PATH. The curl/PowerShell installers also register it with Claude Code automatically when the claude CLI is present; Homebrew installs the binary, so run the claude mcp add line above to connect it.
One-click install:
The Cursor / VS Code / LM Studio buttons install the zero-config uvx setup (your editor prompts to confirm before adding it; needs uv — see above). It runs DuckDuckGo web search with no API key — great to try instantly; image_search/news_search and richer providers need a key (2 min, see Configuration). Claude Desktop: download the .mcpb bundle for your platform and double-click it (Settings → Extensions), or use the uvx line above.
Your AI can now search the web, read full articles, find academic papers, look up patents, and run multi-step research — only from sources you pick.
Why does this exist?
Perplexity gets its citations wrong over a third of the time. It links to papers that don't exist, invents DOIs, and presents SEO spam with the same confidence as peer-reviewed research. ChatGPT's web search isn't much better — it can't tell a blog post from a court filing.
If your work gets cited, published, submitted to a court, or shown to a client — you can't afford "probably real" sources.
This tool fixes the root cause: instead of searching the entire web and hoping, you tell your AI exactly which sources to search. We call these "search lenses" — curated lists of trusted sites for each field.
What you get
What that means for you
Search lenses — choose your sources by field
Your AI only sees the sites you trust (PubMed, SEC.gov, arXiv — not random blogs)
Research tools for every source type
Papers, patents, SEC filings, US court records, economic data, news, web pages, images, full-text reading, grounded answers with citations, structured extraction, and multi-step deep research
Always has a backup
Multiple search engines working together — if one has issues, the others pick up automatically
Reads full articles
Doesn't just give you snippets — extracts and reads entire pages, PDFs, Word docs, even YouTube transcripts and Hacker News threads
Real citations, formatted
Every source comes with a proper APA/MLA citation and a link that actually works
Your queries stay private
Runs on your machine — nobody sees what you're researching. Not us, not anyone.
Paper trail
Every search is logged so you can reproduce your research process months later
Works with Claude, Claude Desktop, Cursor, and any AI assistant that supports tool use.
Who uses this
Academic researchers — "I need a literature review with real DOIs, not made-up citations"
Business analysts — "My deliverable needs sources a client can actually click and verify"
Lawyers — "If I cite a case that doesn't exist, I get fined $50,000"
Journalists — "I need to cross-check government records and court filings, not Perplexity summaries"
Medical researchers — "Clinical decisions based on a health blog could hurt someone"
Graduate students — "I spent 3 hours tracking down a citation my AI invented"
Enterprise teams — "Our competitive research can't go through a third party's servers"
How It Compares
web-researcher-mcp
Perplexity
Scite.ai
Elicit
You pick which sources are searched
Yes (built-in + custom lenses)
No
No
No
Makes up citations
Never — every link is real
~37% incorrect
Rare (journals only)
Rare
Works across all fields
Yes — legal, medical, news, patents, everything
Yes
Journals only
Papers only
Keeps your research private
Yes — runs on your machine
No (they see everything)
No
No
Works inside your existing AI (Claude, Cursor, etc.)
Yes
No (separate app)
Partially
No (separate app)
Can read full articles, not just snippets
Yes — pages, PDFs, Word docs, YouTube
No
No
Limited
Cost
Free forever (open source)
$20/mo
$20/mo
$10-49/mo
When to use what
Perplexity — Quick casual lookups where you don't need to cite your sources
Scite.ai / Elicit — Browsing a specific database of academic papers
web-researcher-mcp — Anything where your reputation is attached to the research: client work, court filings, publications, grant proposals, medical decisions, journalism
Claude built-in search — Quick one-off lookups mid-conversation
What your AI can do with this
Tool
What it does
web_search
Search the web — optionally restricted to only the sources you trust via lenses
scrape_page
Read any URL in full — web pages, PDFs, Word docs, slideshows, YouTube transcripts, Hacker News threads (read natively via the HN API); supports mode: raw for verbatim, unsanitized source (e.g. inspecting JSON or HTML)
search_and_scrape
Search and then read the best results — with quality scoring to surface the most reliable sources
image_search
Find images by size, type, color, or format
news_search
Search recent news with date controls and source filtering
academic_search
Find real papers with real DOIs — authors, citation counts, open-access links
paper_fulltext
Fetch a paper's full text in one call from its DOI, Semantic Scholar ID, or URL — no need to chain academic_search then scrape_page
citation_graph
Walk a paper's citation neighborhood — works it cites and works that cite it, with intent/influence signals
patent_search
Search patent offices (US, Europe, international) with classification codes
filing_search
Search SEC EDGAR for US public-company filings (10-K, 10-Q, 8-K, …) — or pull structured XBRL company facts
legal_search
Search US court opinions and dockets via CourtListener — real cases with real citations
econ_search
Look up economic data — World Bank global development indicators, OECD economic indicators, Eurostat European statistics (all keyless), and FRED US macro series (GDP, CPI, unemployment, rates; requires FRED_API_KEY)
clinical_search
Search ClinicalTrials.gov — clinical-trial registrations with status, phase, sponsor, and whether results are posted (discovery, not medical advice)
monarch_search
Query the Monarch Initiative biomedical knowledge graph — rank diseases and genes by phenotype similarity, look up disease/gene/phenotype entities, traverse gene-disease-phenotype associations
awesome_list_search
Search the ecosyste.ms Awesome API for community-curated "awesome-*" lists on a GitHub topic — structured, filterable coverage (stars, curated-entry count, topics) beyond free-text search
local_search
Search for physical places (restaurants, shops, services, points of interest) by local intent query — structured POI details and descriptions. Requires BRAVE_API_KEY
brand_research
Research a company's complete brand identity — colors (hex), logos, typography, tone of voice, and social handles — from any domain or company name. Returns structured JSON for AI content generation. No API key required; BrandFetch key optional for richer data
company_recon
OSINT company reconnaissance — Certificate Transparency log SANs, Wayback Machine historical URL inventory, derived subdomains, and a web-search company summary. Each phase fails soft and is independently selectable
verify_citation
Check a citation before you rely on it — does it exist, match a real record, and is it retracted or a dead link? Evidence, not a verdict
audit_bibliography
Audit a whole reference list in one pass — paste a CSL-JSON/RIS/BibTeX file (or a session) and get per-entry + corpus-level flags for retracted, dead-link, and unverifiable citations
verify_recommendation
Audit an AI-generated recommendation list (listicle, product ranking) for self-promotion, author conflicts of interest, domain reputation, and dead links — catches GEO-gamed picks. Evidence, not a verdict
archive_source
Capture a fresh Internet Archive (Wayback Machine) snapshot of a URL via Save Page Now so a cited source stays verifiable if the page later changes or disappears — returns snapshot URL + timestamp (write tool)
sequential_search
Multi-step deep research — your AI remembers what it already found and builds on it
get_research_session
Recover a research session after context loss — picks up right where you left off
research_export
Export a research session as a shareable report (markdown or JSON), with full per-step provenance
format_bibliography
Turn collected sources into a formatted bibliography — APA, MLA, BibTeX, RIS, or CSL-JSON (Zotero/EndNote/Mendeley-ready)
research_panel
Ask the same question to a panel of independently configured LLMs and compare answers — consensus, contradictions, and model-unique points, computed deterministically, never smoothed over by an arbiter model
Most tools above are always available. A few activate only when the right provider or config is present: citation_graph and research_panel require at least one configured backing provider; filing_search requires EDGAR_CONTACT_EMAIL; local_search requires BRAVE_API_KEY. Operators can also enable opt-in, consent-gated tools (per-user analytics, long-term memory, shared workspaces, saved-query monitoring) that appear only when their feature is turned on — see docs/TOOLS.md for the authoritative, CI-verified tool list and full schemas.
Ready-made research templates
The server also ships guided prompt templates your AI assistant can pull in with one click — they walk it through a proven, multi-step process so you don't have to spell out every instruction:
Template
What it guides your AI to do
comprehensive-research
Run a structured, multi-step deep dive on a topic
fact-check
Verify a claim against multiple independent sources
competitive-analysis
Size up a company and its market (news, patents, web)
literature-review
Systematically review academic literature on a topic
brand-guidelines
Research a brand and produce use-case-specific creative direction (landing page, email, video brief) — calls brand_research and interprets the structured JSON for you
company-recon
Deep OSINT reconnaissance on a company — maps infrastructure, filings, personnel, and public footprint
curriculum-research
Research a subject's syllabus coverage, institutional climate, and academic-freedom context — calls web_search with the curriculum lens
In most AI apps these show up wherever you pick a prompt or "/" command. The server exposes live status resources (stats://tools, stats://sessions, stats://rate-limits, stats://providers), a lens catalog (lenses://catalog), diagnostics (diagnostics://errors/recent, diagnostics://health), and a large-payload artifact store (research://artifact/{id}) so you — or your AI — can check usage, limits, and which providers are active. See docs/DEPLOYMENT.md for the full list.
Quick Start
Option 1: Homebrew (macOS / Linux — recommended)
bash
brew install zoharbabin/tap/web-researcher-mcp
claude mcp add --scope user web-researcher -- web-researcher-mcp
Homebrew handles trust, updates, and PATH for you — no signing warnings.
Option 2: One-command install (any OS — no dev tools needed)
macOS / Linux:
bash
curl -fsSL https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.sh | sh
Downloads the binary, verifies its SHA-256 checksum against the signed release, puts it on your PATH, and registers it with Claude Code if installed. Customize the install location:
bash
INSTALL_DIR=/opt/tools curl -fsSL https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.sh | sh
Other install methods
AUR (Arch Linux):
bash
# Using any AUR helper (yay, paru, etc.)
yay -S web-researcher-mcp
Or manually: git clone https://aur.archlinux.org/web-researcher-mcp.git && cd web-researcher-mcp && makepkg -si
Nix / NixOS:
bash
# Run without installing
nix run github:zoharbabin/web-researcher-mcp
# Add to your flake inputs
nix profile install github:zoharbabin/web-researcher-mcp
The cask ships the notarized darwin binary (Gatekeeper-clean). Most users want the formula above (brew install zoharbabin/tap/web-researcher-mcp), which the bare name resolves to; pass --cask explicitly for the notarized artifact.
Go install (if you have Go):
bash
go install github.com/zoharbabin/web-researcher-mcp/cmd/web-researcher-mcp@latest
claude mcp add --scope user web-researcher -- web-researcher-mcp
Docker:
bash
# STDIO mode needs -i so the container's stdin stays attached for MCP JSON-RPC
docker run -i --rm \
-e GOOGLE_CUSTOM_SEARCH_API_KEY=YOUR_KEY \
-e GOOGLE_CUSTOM_SEARCH_ID=YOUR_CX \
docker.io/zoharbabin/web-researcher-mcp:latest
Build from source:
bash
git clone https://github.com/zoharbabin/web-researcher-mcp.git
cd web-researcher-mcp
go build -o web-researcher-mcp ./cmd/web-researcher-mcp
Connect to Your AI Assistant
The install script registers with Claude Code automatically. For other apps, add to your AI's config file:
Swap in any provider from the Configuration table by setting SEARCH_PROVIDER and that provider's key. Done — your AI assistant now has access to all research tools.
Configuration
No API key required. DuckDuckGo is the built-in zero-config fallback — install and go. To raise result quality and unlock image/news search, add any one of the providers below. They're all optional and interchangeable — pick whichever you already use or prefer; the server treats them equally.
Search providers
Set SEARCH_PROVIDER=<name> and supply that provider's key. Every provider works with search lenses, and any of them can be combined for automatic failover (see Search Providers).
Each provider has its own free tier, signup flow, and capability mix (images, news, freshness). See docs/PROVIDERS.md for a full comparison (index classification, capability matrix, quick-pick guide) and docs/API_SETUP.md for step-by-step key setup. Set up more than one and the server fails over automatically — see Search Providers.
When SEARCH_PROVIDER is unset, the server uses Google if its keys are present and otherwise falls back to the zero-config DuckDuckGo provider — so it always works out of the box, with or without keys.
Academic Search (Optional — no signup needed)
Academic search providers (OpenAlex, CrossRef) accept a contact email to unlock faster access via the polite pool — no registration, just an email. See docs/API_SETUP.md for setup and docs/DEPLOYMENT.md for the full variable reference.
With these set, academic_search returns real papers with DOIs, authors, citation counts, and open-access PDF links. Without them, it still works but uses web search as a fallback.
Patent Search (Optional)
Patent providers (EPO, USPTO, The Lens) require API keys for structured patent data. See docs/API_SETUP.md for step-by-step setup and docs/DEPLOYMENT.md for the full variable reference.
With these, patent_search returns structured patent data with classification codes, dates, and inventors. Without them, it falls back to web search.
Advanced: HTTP mode, OAuth, and all other settings
HTTP mode, OAuth, rate limiting, cache, scraping, and observability settings are documented in docs/DEPLOYMENT.md.
Under the Hood
Architecture (for developers and contributors)
The full per-package map and the layered diagram (MCP transports → tool dispatch → service layer → infrastructure) live in ARCHITECTURE.md — kept in one place to avoid drift.
Design Principles (for developers)
Zero global state -- all dependencies injected via constructors
Interface-driven -- every external dependency behind an interface for testing and swapping
Bounded concurrency -- explicit semaphores for external API calls
Defense in depth -- SSRF protection, rate limiting, content sanitization at every layer
Fail loud -- errors returned, never swallowed; validation at boundaries
Search Providers
You choose which search engine powers your research. All of them work with lenses.
Provider
Whole-Web
Images
News
Notes
DuckDuckGo
Yes
—
—
Zero-config default (no API key needed); rate-limited for heavy use
Neural/semantic search; also backs academic_search and the optional paid scrape tier
Hacker News
HN only
—
Yes
Zero-config (HN Algolia index); searches HN threads, not the full web
Reddit
Reddit only
—
Yes
Zero-config (public RSS); searches Reddit posts, not the full web
Bluesky
Bluesky only
—
—
Zero-config (public AT Protocol API); searches Bluesky posts, not the full web
GitHub
GitHub only
—
Yes
Zero-config (public REST Search API); searches issues/PRs, not the full web
Multiple Providers (recommended)
Set up multiple search engines so if one has issues, your research doesn't stop:
bash
export SEARCH_ROUTING=brave,google,serper
If Brave is down, it automatically tries Google. If Google is rate-limited, it falls through to Serper. Your research just works.
See docs/PROVIDERS.md for a full provider comparison (index classification, capabilities, free tiers) and docs/DEPLOYMENT.md for advanced routing options (per-topic routing, patent-specific providers, etc.).
Single Provider
If you only have one search API key, that works too — just set it up and go.
Any provider from the Configuration table works the same way — set SEARCH_PROVIDER and its key(s).
Search Lenses
Search lenses let you control which websites your AI is allowed to search. Instead of searching the entire web (and getting blogs, spam, and AI-generated junk), a lens restricts results to only the sources you trust for that topic.
When you (or your AI) use a lens, results come only from the sites in that lens. For example, using the medical lens means your AI searches PubMed, WHO, NIH, and other clinical sources — never health blogs or supplement ads.
Your AI uses lenses automatically when you ask it to. For example: "Search for recent findings on SGLT2 inhibitors using the clinical lens."
Creating Your Own Lens
Create a directory for your custom lenses and add a JSON file for each one:
json
{"name":"my-industry","description":"Only searches sources I trust for my field","domains":["trusted-source.com","industry-journal.org","official-database.gov"],"cx":"","routing":""}
Then point the server to your lens directory:
bash
export CUSTOM_LENSES_PATH=/path/to/my-lenses
Your AI will now have my-industry as an available lens. Custom lenses load after the built-in set — a custom lens with the same name as a built-in one overrides it. You can add up to ~10 domains per lens.
Advanced options (optional — most users can ignore these):
cx — If you have a Google Programmable Search Engine with up to 5,000 domains, put the engine ID here
routing — Force this lens to use a specific search provider (e.g., "google")
Privacy & Security
Your research queries go directly from your machine to the search provider you chose. They never pass through our servers (we don't have servers). The tool runs entirely on your computer.
Add to your MCP config (~/.claude.json). Set SEARCH_PROVIDER and the matching key for whichever provider you use (see the Configuration table) — this example uses Google:
Note: Tool behavior is identical across all connection modes (STDIO and HTTP). The only differences are auth (HTTP requires OAuth) and rate limiting (HTTP enforces per-tenant limits; STDIO has only upstream API quotas). See docs/DEPLOYMENT.md for details.
Performance
Searches come back in under a second. Previously-seen results are cached so repeats are instant. Full article extraction works on 95%+ of the web — including sites that try to block bots. Heavy JavaScript sites get a real browser behind the scenes (automatic, no setup needed).
Development
bash
go build -o web-researcher-mcp ./cmd/web-researcher-mcp # Build
go test -race ./... # Test (with race detector)
make verify # Full CI gate (see Makefile for steps)
The lint, gosec, and govulncheck tools are pinned as go.mod tool directives, so make verify runs them at the exact versions CI uses (no global installs needed). Branch protection requires the Lint, Test, Security, and E2E checks to pass.
See CONTRIBUTING.md for the full development workflow, code style guide, and PR process.
Troubleshooting
Server starts but tools fail with "API key" errors
The server starts even with missing credentials (to allow MCP handshake). Set your API keys in the env block of your MCP client config, not in your shell profile.
Some pages come back empty
For JavaScript-heavy sites, the tool uses a real browser (Chromium). With the binary install it auto-downloads on first use (~200MB). If you already have Chrome installed, set CHROME_PATH to point to it. The Docker image ships with Chromium bundled (CHROME_PATH preset), so JavaScript rendering works out of the box — no download.
Cache serving stale results after upgrade
The disk cache lives at your OS cache directory (e.g., ~/Library/Caches/web-researcher-mcp/ on macOS, ~/.cache/web-researcher-mcp/ on Linux). Delete that directory to clear it, or set CACHE_DIR to a custom path.
Hitting search limits (429 errors)
If your provider's free tier runs out (e.g. Google PSE allows 100 searches/day):
Switch to a different provider — set SEARCH_PROVIDER to any other option (see Configuration); each has its own free tier
Set up multiple providers (e.g. SEARCH_ROUTING=brave,google) — if one is rate-limited, it automatically falls through to the next
Or upgrade your provider's plan
macOS: "Failed to reconnect" / error -32000 after a manual update
This happens only if you replaced the binary by copying new bytes over the existing file in place (cp new /path/to/web-researcher-mcp). On Apple Silicon, macOS caches the binary's ad-hoc code signature against the file, and overwriting it in place can make the next launch get killed before it starts. The official installers (Homebrew, the one-command install.sh, and the Claude Code plugin) avoid this by installing to a fresh file. To fix a manual install, replace it cleanly and re-sign:
