👁 web-researcher-mcp logo

web-researcher-mcp

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.

👁 CI
👁 Go Report Card
👁 Go Reference
👁 Image
👁 Release
👁 Docker
👁 PyPI
👁 web-researcher-mcp MCP server
👁 GitHub Stars

Get started in 30 seconds

Python users — uvx (no compile, any OS):

# 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

from web_researcher_mcp import WebResearcherClient

async with 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 "?")

Full documentation: docs/PYTHON_CLIENT.md

👁 Open In Colab

Sync wrapper (for scripts and notebooks that don't use async):

with WebResearcherClient.sync() as client:
 response = client.web_search("climate change 2024")
 print(response.results[0].title)

macOS (Homebrew):

brew install zoharbabin/tap/web-researcher-mcp
claude mcp add --scope user web-researcher -- web-researcher-mcp

macOS / Linux (no package manager):

curl -fsSL https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.ps1 | iex"

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:

👁 Add to Cursor
👁 Install in VS Code
👁 Add to LM Studio

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.

Using a different MCP client or want to pass API keys? See Connect to Your AI Assistant for the per-app config, and Configuration to pick a search provider.

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.

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"

👁 Image

How It Compares

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

Most tools above are always available. A few activate only when the right provider or config is present: citation_graph requires a citation-capable academic provider (OpenAlex or Semantic Scholar); filing_search requires EDGAR_CONTACT_EMAIL; answer and structured_search require a provider that supports those capabilities (e.g. Exa). Operators can also enable opt-in, consent-gated tools (per-user analytics, long-term memory, shared workspaces) 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:

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)

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:

curl -fsSL https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.ps1 | iex"

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:

INSTALL_DIR=/opt/tools curl -fsSL https://raw.githubusercontent.com/zoharbabin/web-researcher-mcp/main/install.sh | sh

Connect to Your AI Assistant

The install script registers with Claude Code automatically. For other apps, add to your AI's config file:

{
 "mcpServers": {
 "web-researcher": {
 "command": "web-researcher-mcp",
 "env": {
 "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_GOOGLE_API_KEY",
 "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ENGINE_ID"
 }
 }
 }
}

Any provider works — pick one and set its key. For example, Brave (no Google keys needed):

{
 "mcpServers": {
 "web-researcher": {
 "command": "web-researcher-mcp",
 "env": {
 "SEARCH_PROVIDER": "brave",
 "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
 }
 }
 }
}

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/API_SETUP.md for step-by-step setup of every provider and a capability comparison. 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.

Under the Hood

Search Providers

You choose which search engine powers your research. All of them work with lenses.

Multiple Providers (recommended)

Set up multiple search engines so if one has issues, your research doesn't stop:

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/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.

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.

Built-in Lenses

You can also create your own lenses for any field — just list the domains you trust.

How it works

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."

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.

Setup for Each AI App

Claude Code

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:

{
 "mcpServers": {
 "web-researcher": {
 "command": "/path/to/web-researcher-mcp",
 "env": {
 "SEARCH_PROVIDER": "google",
 "GOOGLE_CUSTOM_SEARCH_API_KEY": "AIza...",
 "GOOGLE_CUSTOM_SEARCH_ID": "017..."
 }
 }
 }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
 "mcpServers": {
 "web-researcher": {
 "command": "/path/to/web-researcher-mcp",
 "env": {
 "GOOGLE_CUSTOM_SEARCH_API_KEY": "AIza...",
 "GOOGLE_CUSTOM_SEARCH_ID": "017..."
 }
 }
 }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
 "mcpServers": {
 "web-researcher": {
 "command": "/path/to/web-researcher-mcp",
 "env": {
 "GOOGLE_CUSTOM_SEARCH_API_KEY": "AIza...",
 "GOOGLE_CUSTOM_SEARCH_ID": "017..."
 }
 }
 }
}

HTTP Mode (Teams / Shared Server)

For teams that want one shared instance everyone connects to:

PORT=3000 \
OAUTH_ISSUER_URL=https://auth.example.com \
OAUTH_AUDIENCE=https://api.example.com \
./web-researcher-mcp

Then connect any AI app to http://localhost:3000/mcp/.

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

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

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for code style guidelines, development workflow, and how to submit pull requests.

Documentation

License

MIT

Star History

👁 Star History Chart

Built with Go and the Model Context Protocol

If you're tired of AI making things up, give this a try — and a ⭐ if it helps.