WebSearch MCP Server

websearch-mcpserver

轻量级 Web Search MCP Server — 零 API Key 即可运行

English · 中文

用 Go 编写的 MCP 搜索服务。内置百度网页、Bing、DuckDuckGo 等通用引擎、Parallel / AnySearch / Exa / Firecrawl 四个零 Key 托管 MCP 上游和 9 个学术引擎，搜索、评分、缓存全部在本地完成。可作为 MCP 工具接入 Claude Code、Qwen Code、Cursor，也可作为 Go 模块嵌入自有服务。

免费、国内可用、结果可直接给 LLM 消费。 无 Key 也能搜；有 Key 才用 Key。

架构一览

分层设计：客户端最多面对 5 个 MCP 工具；引擎组由 mode 组装；评分、缓存、代理、抓取都在本进程内完成，查询不会经过第三方聚合服务。

更完整的回退链、代理检测与嵌入方式见 docs/architecture.md。

面向 LLM 的工具链

五个检索工具互相衔接；已保存的长搜索、网页/PDF 正文通过 cleanfetch 分段读回，无需客户端访问容器文件。读取从 offset=0 开始，按 next_offset 续读到 eof=true。

核心特性

搜索与评分管线

结果不是原始聚合。多引擎回传后在本地做去重、融合排名和多样性重排，再可选生成摘要：

设计背景与目标

现成的 MCP 搜索方案各有短板：厂商服务（Tavily / Exa 等）要 Key、按量付费、数据过第三方、国内访问不稳；自建 SearXNG 要维护 Python 服务，结果是未优化的原始聚合。本项目把这些能力收回本地：单二进制自带多引擎融合、9 大学术源、抓取与 PDF 解析，让搜索成为 LLM 的免费、国内可用、结果可直接消费的基础能力。

完整的立项动机、与现成方案的逐维度对比、以及设计原则（本地优先隐私默认 / 零成本起步 / 丰简由人 / 解耦可组合 / 面向 LLM 的完整工具链 / 场景化优化）见 docs/design.md。

快速开始

# 1. 下载二进制: https://github.com/daidaiJ/websearch-mcpserver/releases
# 2. 启动（无需手写配置，无需 API Key）
# Windows 开机自启动 可选
./websearch-mcpserver.exe install
#
#    首次 install 会在可执行文件目录自动生成一份可编辑的预设 config.yaml 和 autostart.vbs
./websearch-mcpserver start
# 或者点击
autostart.vbs
# 3. 注册到 MCP 客户端（见 docs/installation.md）

「零配置」= 首次启动自动生成与 config.example.yaml 相同的预设 config.yaml，改端口 / Key / 模式都改这一份文件。默认只监听 127.0.0.1；开放网卡（host: 0.0.0.0）时建议配置 auth_token 保护业务端点。

想用零 Key 托管 MCP 级联，把该文件的 mode 改为 mcphub 即可（mcp_hub.enabled 默认为开）。

或通过 MCP Hooks 实现会话自动启停（Qwen Code 示例，完整说明见 docs/installation.md）：

{
  "hooks": {
    "SessionStart": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "/path/to/websearch-mcpserver start", "timeout": 10000 }] }],
    "SessionEnd":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "/path/to/websearch-mcpserver stop",  "timeout": 10000 }] }]
  }
}

搜索模式速览

mode 一个字段决定引擎组合：零 Key 推荐 mcphub（托管 MCP 级联，失败冷却 + 本地引擎/Bing 降级）；有 API Key 推荐 apipool（多供应商 Key 池轮转，失败自动切换，网页引擎兜底）。engine 适合只依赖本地网页引擎、不需要 MCP 的场景；baidu / tavily / exa / anysearch / doubao / yuanbao 为单供应商直连（有 Key 才参与，主引擎失败自动回退）；hybrid 全引擎并发；mcphub 支持 rotation_engines 把本地引擎加入轮转、按代理可用性自动启用/跳过需代理上游。无 Key 时单供应商模式自动降级为 engine。

各模式的参与引擎、获取 Key 入口、sk_list 多 Key 轮询与逐引擎限流口径见 docs/search.md。

mcphub 的四个内置 preset：

• 级联顺序默认 parallel → anysearch → exa → firecrawl，单次请求命中一个；失败冷却 60s 后切换，这是路由与降级，多家的结果不会合并返回。
• 全部失败后按 fallback_engines（默认 bing → so360，未启用的引擎自动跳过，so360 默认关闭）降级，最终仍由 smartsearch 回退 Bing。
• 每个上游可配 api_key / sk_list，留空走匿名档；鉴权失败自动换下一把 Key，连接/超时则冷却该 server 并级联；exa / firecrawl 仅在检测到代理时参与轮转，代理恢复后自动回归。
• rotation_engines 可把本地引擎（如 so360）加入主轮转，分摊匿名限流。
• fetch_mode: off / fallback / prefer 让 cleanfetch 复用同一批 MCP 抓取（mode=mcphub 时共用搜索 Hub 的冷却与 Key 池）；PDF 仍走本地解析，SSRF / HEAD 预检不跳过。

本机控制中心（可选，默认关闭）

dashboard.enabled: true 后，本机浏览器访问 http://127.0.0.1:8338/dashboard/。四个页面：总览 KPI 与客户端用量归组、搜索源健康与失败构成、请求级调用链（可筛选、可导出 CSV）、备份后写入白名单配置；全程被动观测，失败分类只报告，不干预调用。

启用即把 dashboard.example.yaml 复制为 config.yaml 同目录的 dashboard.yaml（首次 start / install 自动生成并默认启用，含随机本机管理员口令）；删除该文件并重启即完整回退，运行时零遥测开销。隐私默认：查询只存哈希 + 主题等脱敏元数据，密钥与查询原文永不落库、接口永不回显；默认仅本机 loopback 可读，写操作需 admin_password。另提供 GET /metrics（Prometheus/OpenMetrics 文本，只读、只含脱敏聚合），需 dashboard.enabled: true，未启用返回 503。

页面明细、全部配置键、快捷方式落位、安全模型与调用归属见 docs/dashboard.md。

文档导航

各文档均为中文默认，同名 .en.md 为英文版。

相关项目

• web-researcher — 配套 Qwen Code 扩展，将网络调研卸载到子智能体，保持主模型上下文干净（详见 docs/architecture.md）