web-search-mcp

为本地大语言模型（LLM）提供外部网页搜索和页面抓取功能，以 MCP 工具和 CLI 的形式呈现。该实现优先使用 Playwright，采用异步方式，默认启动系统安装的 Chromium 二进制文件。设计历史记录在 docs/IMPLEMENTATION_PLAN.md 中。

工具

• search(provider, context) 在 duckduckgo（默认）、google 或 yandex 上运行基于浏览器的搜索，并返回最多 5 个自然搜索结果的 URL。

• fetch(urls) 抓取 1..5 个 URL，并返回浏览器渲染后的 HTML，包含每个 URL 的 pages、errors 和 truncated 字段。

context 特意设计为搜索查询字符串，以保持调用者兼容性。

Related MCP server: Web Search MCP

设置

uv sync
chromium --version

如果 Chromium 安装在非标准位置，请设置 PLAYWRIGHT_CHROMIUM_EXECUTABLE=/path/to/chromium。

使用方法

通过 stdio 运行 MCP 服务器：

uv run web-search serve-mcp

直接运行 CLI：

uv run web-search search --context "python async playwright"
uv run web-search fetch https://example.com

暴露 HTTP 传输而非 stdio：

uv run web-search serve-mcp --transport streamable-http --host 127.0.0.1 --port 8000

设计说明

• 每个进程共享一个浏览器，每个请求使用一个新的无痕上下文。

• Playwright 启动系统 Chromium 二进制文件，而不是 Playwright 下载的浏览器包。

• 系统 Chromium 可与 Playwright 配合使用，而测试的系统 Firefox 构建在启动后立即退出。因此，本仓库将系统 Chromium 作为支持的主机浏览器路径。

• 浏览器冒烟测试应从普通主机 shell 运行。受限沙箱即使在主机浏览器工作正常时也可能阻止 Chromium 启动。

• 全局导航并发上限为 3。

• 超时设置：每页 15s，search 总计 20s，fetch 总计 35s。

• SSRF 防护：仅限 http/https，无嵌入式凭据，在导航前和浏览器子请求时阻止回环/私有/链路本地/保留 IP。

• JavaScript 挑战页面有 10s 的有限稳定窗口；不包含验证码破解、隐身指纹识别或特定站点的绕过逻辑。

• HTML 每个 URL 上限为 1 MiB；超大的响应会被截断并在 truncated 中报告。

• v1 版本不参考 robots.txt。

开发

source .venv/bin/activate
pytest

解析器测试针对保存的 HTML 固定数据运行；选择器漂移是预期的维护成本。