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

From npm:

npx -y mcp-web-search-tool

Point your MCP client at npx with args ["-y", "mcp-web-search-tool"] and pass BRAVE_API_KEY through the client's env block.

From source:

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

Search tools return an untrusted-content banner, a Markdown rendering for the model, and a fenced JSON block with the structured payload; fetch_url returns the readable page text plus a links block. 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<SearchResponse> {
    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 suite
npm run lint         # eslint + prettier
npm run typecheck    # tsc --noEmit
npm run format
npm run build

CI runs lint, format check, type check, build, and tests on Node 22 and 24; a Docker image build runs when the image inputs change. 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