AI导哈

网页搜索工具

MCP Web Search是一个本地优先的网页搜索和URL资源加载工具，支持多提供商搜索和URL内容提取，无需API密钥。

  • by tickernelz
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 tickernelz/mcp-web-search

使用说明

MCP网络搜索

用于网络搜索和URL/资源加载的MCP服务器。默认情况下，它在没有API密钥的情况下工作，并保持本地优先：搜索使用免费提供商， fetch_url 从URL中提取有用内容，二进制/媒体下载仅在明确请求时发生。

特性

  • search_web -多提供商网络搜索，可在DuckDuckGo、Bing和SearXNG之间自动回退。
  • fetch_url -用于HTML、PDF、文本、Markdown、JSON、XML、CSV、媒体元数据和支持的特定于站点的URL的通用URL/资源加载器。
  • 用一个干净的归一化输出 content 字段加元数据、分页、链接、媒体、附件和警告。
  • 通过Reddit JSON端点提取Reddit线程，而不是脆弱的Reddit HTML抓取。
  • 长资源分页 max_length, start_index，以及 next_start_index.
  • 可选的HTML链接/媒体摘要。
  • 可选的本地下载工件 download: true.
  • 本地主机、私有IP、链路本地范围、IPv6私有范围和不安全重定向的SSRF保护。
  • 不需要付费API。

需求

  • Node.js 18+
  • 仅当您使用Bing提供商时才使用Chrome/Chromium

MCP配置

克劳德代码

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@zhafron/mcp-web-search"]
    }
  }
}

OpenCode

{
  "mcp": {
    "web-search": {
      "type": "local",
      "command": ["npx", "@zhafron/mcp-web-search"]
    }
  }
}

自定义配置

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@zhafron/mcp-web-search"],
      "env": {
        "DEFAULT_SEARCH_PROVIDER": "duckduckgo",
        "SEARXNG_URL": "http://localhost:8099"
      }
    }
  }
}

工具

搜索web

通过一个提供商或回退链搜索网络。

输入：

{
  "q": "openai codex reddit review",
  "limit": 10,
  "lang": "en",
  "provider": "duckduckgo"
}

选项：

选项 描述
q 搜索查询
limit 结果数量，1-50
lang 默认搜索语言 en
provider 可选提供者： duckduckgo, bing，或 searxng

输出：

{
  "items": [
    {
      "title": "Example Result",
      "url": "https://example.com",
      "snippet": "Result summary...",
      "source": "duckduckgo"
    }
  ],
  "providerUsed": "duckduckgo",
  "fallbackUsed": false,
  "triedProviders": ["duckduckgo"]
}

回退顺序：

  • 鸭鸭搜→ SearXNG→ Bing
  • SearXNG→ 鸭鸭搜→ Bing
  • Bing → 鸭鸭搜→ SearXNG

fetch_url

获取一个URL，并在规范化的信封中返回提取的内容和元数据。

输入：

{
  "url": "https://example.com/article",
  "format": "markdown",
  "max_length": 8000,
  "start_index": 0,
  "include_links": true,
  "include_media": true
}

选项：

选项 描述
url 要获取的URL
format markdown, text, html, json, raw，或 metadata
max_length 最大返回内容字符数，默认25000
start_index 从此字符索引开始内容
engine auto, http，或 browser；浏览器回退保留用于未来的可选支持
include_links 包含HTML页面的提取链接
include_media 包含HTML页面的提取图像/视频/音频参考
include_comments 包括支持注释的站点适配器的注释，Reddit默认为true
comment_limit 可评论适配器的最大评论数，最多100条
comment_sort top, best, new，或 controversial
max_depth 最大注释嵌套深度
timeout_ms 请求超时覆盖
fresh 绕过内存缓存
download 将原始提取的字节保存到托管的本地文件中，并在中返回 attachments；默认值为false
download_dir 可选的下载输出目录；默认为系统临时目录
download_ttl_seconds 清理托管下载的TTL，默认86400秒
max_download_bytes 响应/下载字节上限覆盖，另加上限 MAX_BYTES

输出：

{
  "url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "title": "Example Article",
  "content_type": "text/html",
  "resource_type": "html",
  "format": "markdown",
  "content": "# Example Article\n\n...",
  "metadata": {
    "status": 200,
    "content_type": "text/html",
    "byte_length": 12345,
    "extractor": "html",
    "fetched_at": "2026-05-03T00:00:00.000Z"
  },
  "links": [],
  "media": {
    "images": [],
    "videos": [],
    "audio": []
  },
  "truncated": false,
  "original_length": 1200,
  "start_index": 0,
  "next_start_index": null,
  "warnings": []
}

支持的资源

资源 行为
HTML页面 提取可读的文章内容、标题、元数据、可选链接和可选媒体引用
文本和Markdown 直接返回支持分页的文本
JSON Pretty在以下情况下打印JSON format 是 json 或在请求时显示类似文本
类似XML和CSV的文本 作为文本/数据内容返回
PDF 提取文本和PDF元数据
Images 默认返回元数据；仅保存文件 download: true
音频和视频 默认返回元数据；仅保存文件 download: true
档案和二进制文件 默认情况下返回元数据；仅在明确请求时下载；档案不是自动提取的
Reddit线程 使用Reddit JSON端点，可以包含有限制的评论

本地下载

fetch_url 默认情况下，不会将二进制/媒体文件下载到磁盘。这避免了意外的磁盘使用和任意web内容的持久本地副本。

使用 download: true 当您需要其他工具可用的原始文件时：

{
  "url": "https://httpbin.org/image/png",
  "format": "metadata",
  "download": true,
  "download_ttl_seconds": 86400
}

下载附件如下：

{
  "kind": "download",
  "path": "/tmp/mcp-web-search/downloads/mcp-fetch-id-image.png",
  "filename": "mcp-fetch-id-image.png",
  "original_filename": "image.png",
  "content_type": "image/png",
  "resource_type": "image",
  "byte_length": 8090,
  "sha256": "...",
  "expires_at": "2026-05-04T00:00:00.000Z"
}

下载安全行为：

  • 下载仅限选择加入。
  • 文件是用 0600 权限。
  • 文件名经过净化，并以托管工件ID作为前缀。
  • SHA-256返回进行验证。
  • 过期的托管工件通过sidecar元数据进行清理。
  • 清理仅涉及配置的下载目录中的托管工件。
  • 档案从不自动提取。

Reddit线程提取

Reddit线程URL由站点适配器处理，并通过Reddit JSON端点获取。

输入示例：

{
  "url": "https://www.reddit.com/r/codex/comments/abc123/gpt55_is_so_good/",
  "include_comments": true,
  "comment_limit": 30,
  "comment_sort": "top",
  "max_depth": 2
}

输出使用 resource_type: "site" 和 metadata.extractor: "reddit-thread".

Reddit公共JSON仍然可以根据Reddit、subreddit规则和请求频率进行速率限制或返回403/429。发生这种情况时，请稍后重试或降低请求频率。

提供商

提供程序 需要API密钥 注释
DuckDuckGo 否 默认，简单，无需浏览器
Bing 否 通过Puppeter使用铬/铬
SearXNG 否 自托管高容量使用的最佳选择

环境变量

变量 默认值 描述
DEFAULT_SEARCH_PROVIDER duckduckgo 默认搜索提供程序： duckduckgo, bing，或 searxng
SEARXNG_URL http://localhost:8099 SearXNG实例URL
HTTP_TIMEOUT 15000 请求超时（毫秒）
MAX_BYTES 20971520 最大获取响应/下载大小
MCP_COMPAT_MODE unset 设置为 legacy 简化 tools/list 具有弱发现解析器的MCP客户端的模式

SearXNG设置

SearXNG是一个免费的自托管元搜索引擎。

使用Docker快速设置：

mkdir -p ~/docker/searxng

创建 ~/docker/searxng/settings.yml 启用JSON后，运行SearXNG容器。重要的设置是 search.formats 包含两者 html 和 json.

相关设置示例：

search:
  formats:
    - html
    - json

然后设置：

export SEARXNG_URL="http://localhost:8099"

Bing提供商的Chrome设置

OS 命令
Ubuntu/Debian sudo apt install chromium-browser
Fedora sudo dnf install chromium
拱门 sudo pacman -S chromium
macOS brew install --cask google-chrome

自定义路径：

export CHROME_PATH="/path/to/chrome"

MCP发现兼容性

一些MCP客户端的模式解析器很弱，在数组值JSON模式节点上发现时会失败，例如 enum 或 required.

如果发现失败，请设置：

export MCP_COMPAT_MODE="legacy"

这只会简化广告宣传 tools/list 模式。工具执行行为保持不变。

URL安全

fetch_url 在获取和遵循重定向之前阻止不安全的目标。

被阻止的目标包括：

  • 本地主机名
  • .localhost 和 .local 主机名
  • 私有IPv4范围
  • IPv4环回、链路本地、运营商级NAT、基准、组播和选定的特殊使用范围
  • 解析为被阻止的IPv4范围的IPv4映射IPv6地址
  • IPv6环回、未指定、唯一本地、多播和链路本地范围
  • 重定向到被阻止的地址

HTTP传输在连接之前解析和验证地址，然后连接到经过审查的地址，同时保留原始主机/SNI以进行正常的HTTPS行为。

存储库结构

  • src/server.ts -MCP服务器和工具模式
  • src/providers/ -搜索提供商
  • src/fetch/ -URL/资源加载管道
  • src/fetch/content/ -共享内容助手，如Markdown转换和可读性回退
  • src/fetch/extractors/ -用于HTML、文本/数据、PDF和媒体元数据的资源提取器
  • src/fetch/site-adapters/ -特定于域的提取器，如Reddit线程
  • src/utils/ -共享公用设施
  • test/ -节点测试运行器测试

故障排除

问题 解决方案
未找到Chrome 安装Chrome/Chromium或设置 CHROME_PATH
SearXNG 403 在中启用JSON API settings.yml
超时 增加 HTTP_TIMEOUT 或通过 timeout_ms
MCP发现错误： 'list' object has no attribute 'get' 设置 MCP_COMPAT_MODE=legacy
Reddit 429或403 Reddit速率限制或阻止JSON端点；稍后重试或降低请求频率
输出中缺少下载 设置 download: true；默认情况下禁用下载
下载因太大而被拒绝 增加 max_download_bytes 在服务器上限或加薪范围内 MAX_BYTES

许可证

麻省理工学院

相关 MCP