MCP Web Search Tool

MCP Web Search Tool

一个 MCP 服务，为助手提供实时网页搜索、整页阅读和来源引用。使用 Stdio 传输、支持可插拔的提供商，且不依赖抓取器。

快速开始 · 工具 · 配置 · 客户端 · 安全 · 更新日志

---

概述

提供五种工具：web_search、news_search、image_search、fetch_url、list_providers。搜索会返回带有稳定 ID 的排序摘要；fetch_url 可读取任意 ID 对应的页面。Brave Search 是主要提供商；DuckDuckGo 无需密钥即可作为备用选项运行。

要求

Node.js	>= 20.18（使用原生 fetch）
npm	>= 10
Brave Search API 密钥	可选。未提供密钥时，DuckDuckGo 会处理 web_search。news_search 和 image_search 需要密钥。

快速开始

通过 npm：

npx -y mcp-web-search-tool

将 MCP 客户端指向带有参数 ["-y", "mcp-web-search-tool"] 的 npx，并通过客户端的 env 块传入 BRAVE_API_KEY。

从源代码运行：

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

使用 Docker 运行：

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

有关 Claude Desktop、Claude Code、Codex、VS Code、Cursor 或 Windsurf 的集成，请参阅 MCP_CLIENTS.md。

---

工具

搜索工具会返回不可信内容横幅、供模型使用的 Markdown 呈现内容，以及包含结构化数据的围栏 JSON 代码块；fetch_url 会返回易读的页面文本和链接块。发生错误时，会返回包含可执行提示的 isError: true 内容；只有调用未知工具时才会抛出协议错误。

web_search

实时网页搜索。优先用于获取当前信息且有来源支持的答案。

参数	类型	描述
search_term	string，必填	查询字符串。
provider	enum	"brave search" 或 "duckduckgo"。设置了密钥时默认为 Brave，否则默认为 DuckDuckGo。
count	int（1–20）	结果数量。默认值为 10。
offset	int	分页偏移量（仅限网页搜索）。
cursor	string	来自先前响应的不透明游标。
freshness	string	pd（24 小时）、pw（一周）、pm（一个月）、py（一年）或 YYYY-MM-DDtoYYYY-MM-DD。
country	string	ISO 国家代码。
search_lang	string	UI 语言，例如 en。
safesearch	enum	off、moderate、strict。
include_domains	string[]	将结果限制为这些主机。
exclude_domains	string[]	排除来自这些主机的结果（按主机名后缀匹配）。

news_search

近期新闻，包含来源名称和发布日期。仅限 Brave。

image_search

包含缩略图的图片结果。仅限 Brave。

fetch_url

读取搜索结果或任意 http(s) URL。传入先前搜索返回的结果 ID（首选）或完整 URL。

参数	类型	描述
id_or_url	string	结果 ID（例如 r_a1b2c3d4e5f6）或完整的 http(s) URL。
url	string	id_or_url 的已弃用别名。
max_chars	int（200–200 000）	返回字符数的软上限。默认值为 8000。
cursor	string	来自先前响应的游标，用于继续阅读。

返回页面标题、易读文本（移除脚本、样式、导航、页脚和侧边栏）、前 25 个外链、HTTP 状态、内容类型、字节长度，以及内容被截断时的 nextCursor。

拒绝非 http(s) 协议，以及解析为私有、环回、链路本地、多播或 IPv4 映射 IPv6 私有地址的任何主机。详情：SECURITY.md。

list_providers

返回已注册的提供方和当前默认提供方。如果不确定本次会话是否可用 news_search 或 image_search，请调用一次。

---

配置

所有配置均由环境变量控制。参考： .env.example。

变量	默认值	用途
BRAVE_API_KEY	空	Brave Search API 密钥。未设置时使用 DuckDuckGo。
MAX_RESULTS	10	默认结果数量（限制在 1–50 之间）。
REQUEST_TIMEOUT	10000	每个请求的超时时间，单位为 ms（1 000–60 000）。
DEFAULT_PROVIDER	auto	强制使用指定的提供方（例如 duckduckgo）。
ALLOW_KEYLESS	true	设为 false 时，如果未设置 BRAVE_API_KEY，服务将拒绝启动。
CACHE_MAX_ENTRIES / CACHE_TTL_MS	256 / 300000	搜索缓存。
FETCH_CACHE_MAX / FETCH_CACHE_TTL_MS	128 / 600000	URL 抓取缓存。
FETCH_TIMEOUT_MS / FETCH_MAX_BYTES	15000 / 2000000	fetch_url 每个请求的预算。
RESULT_ID_CACHE_MAX / RESULT_ID_TTL_MS	2000 / 3600000	fetch_url 可解析的结果 ID 数量及其有效时长。

---

项目结构

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

添加提供方

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;
  }
}

在 SearchProviderFactory.setupDefaults 中注册。调用每个条目的 mintResultId(url) 时，会自动生成结果 ID。

---

开发

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 会在 Node 22 和 24 上运行 lint、格式检查、类型检查、构建和测试；当镜像输入发生变化时，会构建 Docker 镜像。测试涵盖 LRU+TTL 缓存、HTML 提取器、DuckDuckGo 解析器、搜索服务缓存、HTTP 重试/退避、SSRF 防护、域名匹配和结果 ID 解析器。

---

提示词示例

• “今晚的 NBA 比赛结束后，分析师们对 MVP 之争有何看法？”
• “总结 RAG benchmarks 2025 的前三条结果，并提取第一篇论文的摘要。”
• “查找 Webb telescope 最新深空场的图片，然后打开 NASA 页面并引用图片说明。”
• “柏林现在的天气怎么样？”

---

许可证

MIT 许可证

开发者

作者：Soroush Yousefpour

© 保留所有权利。

YouTube 视频

Claude 使用 MCP Web Search Tool 的简短演示：

Claude + MCP Web Search – 现场演示

Medium 文章

项目背景及其工作原理：

MCP Web Search Tool 深入解析

支持