MCP Web Search Tool

An MCP server that gives an assistant live web search, full-page reading, and source citations. Stdio transport, pluggable providers, no scraper dependencies.

Quick start · Tools · Configuration · Clients · Security · Changelog

Overview

Five tools: `web_search`, `news_search`, `image_search`, `fetch_url`, `list_providers`. Search returns ranked summaries with stable ids; `fetch_url` reads the page behind any id. Brave Search is the primary provider; DuckDuckGo runs without a key as a fallback.

Requirements

Quick start

git clone https://github.com/gabrimatic/mcp-web-search-tool.git
cd mcp-web-search-tool
npm install
cp .env.example .env   # edit BRAVE_API_KEY if you have one
npm run build
npm start

Run with Docker:

docker build -t mcp-web-search .
docker run --rm -i -e BRAVE_API_KEY mcp-web-search

For Claude Desktop, Claude Code, Codex, VS Code, Cursor, or Windsurf integration, see `MCP_CLIENTS.md`.

Tools

Each tool returns two content blocks: a Markdown rendering for the model and a fenced JSON block with the structured payload. Errors come back as `isError: true` content with an actionable message; only unknown-tool calls throw a protocol error.

`web_search`

Live web search. Use first for current, source-backed answers.

`news_search`

Recent news with source name and publish date. Brave only.

`image_search`

Image results with thumbnails. Brave only.

`fetch_url`

Reads a search result or arbitrary `http(s)` URL. Pass a result id from a previous search (preferred) or a full URL.

Returns the page title, readable text (scripts, styles, nav, footer, and aside stripped), the first 25 outbound links, HTTP status, content-type, byte length, and a `nextCursor` when truncated.

Refuses non-`http(s)` schemes and any host that resolves to a private, loopback, link-local, multicast, or IPv4-mapped IPv6 private address. Details: `SECURITY.md`.

`list_providers`

Returns the registered providers and the current default. Call this once if you are unsure whether `news_search` or `image_search` are available in this session.

Configuration

All configuration is environment-driven. Reference: `.env.example`.

Project layout

src/
├── index.ts                    MCP server: tool registry, dispatch, rendering
├── config.ts                   env loader, validation, defaults
├── providers/
│   ├── SearchProvider.ts       abstract contract and shared types
│   ├── SearchProviderFactory   registry and default selection
│   ├── BraveSearchProvider     web/news/images via Brave API
│   └── DuckDuckGoProvider      keyless HTML-lite fallback
├── services/
│   ├── SearchService.ts        provider dispatch, LRU+TTL cache
│   └── FetchService.ts         safe URL fetch, readable extraction
└── utils/
    ├── http.ts                 native fetch, retry/backoff/timeout
    ├── html.ts                 zero-dep HTML to text + links
    ├── cache.ts                LRU+TTL cache
    └── ids.ts                  stable result-id minting and resolution
tests/                          vitest suite

Add a provider

import { SearchProvider, SearchResponse, SearchOptions } from './SearchProvider.js';

export class MyProvider extends SearchProvider {
  getName() { return 'My Provider'; }
  override requiresApiKey() { return true; }
  async search(query: string, _opts: SearchOptions = {}): Promise {
    const out = this.emptyResponse(query, 'web');
    out.results = mapped; // shape: SearchResult[]
    return out;
  }
}

Register it in `SearchProviderFactory.setupDefaults`. Result ids are minted automatically when you call `mintResultId(url)` on each entry.

Development

npm run dev          # tsx watch mode
npm test             # vitest (23 tests)
npm run lint
npm run format
npm run build

CI runs on Node 20, 22, and 24, plus a Docker image build. Tests cover the LRU+TTL cache, HTML extractor, DuckDuckGo parser, search-service caching, HTTP retry/backoff, SSRF guard, domain match, and the result-id resolver.

Example prompts

• _"What are analysts saying about the MVP race after tonight's NBA games?"_
• _"Summarise the top three results for `RAG benchmarks 2025` and pull the abstract from the first paper."_
• _"Find images of the Webb telescope's latest deep field, then open the NASA page and quote the caption."_
• _"What's the weather in Berlin right now?"_

License

MIT License

Developer

By Soroush Yousefpour

© All rights reserved.

YouTube Video

A short demo of MCP Web Search Tool with Claude:

Claude + MCP Web Search – Live Demo

Medium Article

Background on the project and how it works:

Deep Dive into MCP Web Search Tool

Support