mcp-web-research

@opafex/mcp-web-research

MCP server for web research — search the web, fetch pages as clean text, pull named sections out of a page, compare pages side by side, and run a two-stage "search then read the top results" pass.

No LLM is involved: research_topic and compare_pages organise extracted text, they do not generate it. Every page fetch is SSRF-checked, including every redirect hop.

Search uses the Brave Search API (free tier available). Without a key, the four page tools still work and the two search tools return an error telling you which variable to set.

Installation

npx -y @opafex/mcp-web-research

Requires Node.js 20+. No other dependencies to install.

Quick Start

Claude Code

claude mcp add web-research -e BRAVE_SEARCH_API_KEY=your-key -- npx -y @opafex/mcp-web-research

Or add it to .mcp.json in your project root:

{
  "mcpServers": {
    "web-research": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-web-research"],
      "env": {
        "BRAVE_SEARCH_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop

Add the same block to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "web-research": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-web-research"],
      "env": {
        "BRAVE_SEARCH_API_KEY": "your-key"
      }
    }
  }
}

Omit BRAVE_SEARCH_API_KEY to run with the page tools only.

Tools

web_search

Result URLs that fail the SSRF check (below) are dropped before they are returned.

[
  {
    "title": "Model Context Protocol",
    "url": "https://modelcontextprotocol.io/",
    "snippet": "An open protocol that enables seamless integration between LLM applications and external data sources and tools."
  }
]

fetch_webpage

Scripts, styles, <nav> and <footer> are removed. finalUrl is included when the page was reached through redirects.

{
  "title": "Example Domain",
  "text": "Example Domain\nThis domain is for use in illustrative examples in documents.",
  "url": "http://example.com/",
  "fetchedAt": "2026-10-24T12:00:00.000Z"
}

research_topic

Key points are the sentences that mention the topic's words, up to five per source. A source that cannot be fetched falls back to its search snippet.

extract_structured_data

For each field, returns the first line mentioning it and the ten lines after, up to 1,000 characters — or No "<field>" section found on page. This is heading matching, not a schema extractor.

compare_pages

A page that fails to fetch is listed with "(fetch failed)" and the reason; the others are still compared.

Resources

Search providers

About the DuckDuckGo option. It parses the results page at html.duckduckgo.com. That is not an API: it breaks whenever DuckDuckGo changes its markup, it may be rate-limited or blocked, and DuckDuckGo's terms do not permit automated querying. It sends this server's honest user agent rather than pretending to be a browser, which makes blocking more likely. It is kept for personal experimentation; if you turn it on, you are responsible for complying with DuckDuckGo's terms. Use Brave for anything you depend on.

Environment Variables

Security

The page tools fetch URLs chosen by a model, from the machine the server runs on. Without protection, that machine's private network and cloud metadata service are one tool call away (server-side request forgery). Every fetch is checked first, and refused if:

• the scheme is not http or https;
• the host is localhost, *.localhost, or a cloud metadata name (metadata.google.internal);
• the host is a literal IP — IPv4, or bracketed IPv6 — in a non-public range. Odd IPv4 spellings (http://2130706433/, http://0x7f.1/) are normalised before the check;
• any address the hostname resolves to, IPv4 (A) or IPv6 (AAAA), is in a non-public range. One public A record does not excuse a private AAAA record;
• the hostname cannot be resolved. The check fails closed: an address that could not be checked is not fetched.

Blocked ranges:

Redirects are followed by hand, and every hop is checked again — at most 5 hops. A public page that redirects to http://169.254.169.254/ is refused before the second request is made. Search result URLs are checked too, and dropped if they fail.

Known limit — DNS rebinding. The check resolves the hostname, then fetch resolves it again to connect. A hostile DNS server with a very short TTL could answer the two lookups differently. Closing that gap means pinning the connection to the checked address, which Node's built-in fetch does not expose without an extra dependency. If this server runs somewhere with sensitive internal services, also limit what it can reach at the network level (container network policy, egress firewall).

Limits

• Text only. Pages must be text/*, application/xhtml+xml or application/json; PDFs, images and other binary types are refused.
• No JavaScript. Pages are fetched as served. Content rendered client-side will be missing.
• Regex-based HTML parsing. Fast and dependency-free, but not a full HTML parser; unusual markup can leak into the text.
• Heuristic extraction. research_topic key points and extract_structured_data sections are keyword matching, not understanding.
• In-memory cache, per process, lost on restart.
• UTF-8 assumed. Pages in other encodings may decode with replacement characters.
• Not a crawler. No robots.txt handling; it fetches the URLs it is given.

Development

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (no build needed)
npm test         # Run tests (no network — fetch and DNS are faked)
npm start        # Run compiled server

Contributing

Found a bug or have a feature request? Open an issue.

Pull requests welcome — see the main repo for development setup.

License

MIT — see LICENSE.