multsearch-mcp

Claude Code 双路联网搜索 MCP

两条独立搜索路径交叉验证 · 信源显式回传 · 国内可用

这是什么

一个为 Claude Code 设计的本地 MCP 服务器。装上之后，Claude 回答前会真的去网上查，并把信源显式带回来，而不是凭印象瞎答。

核心是两条独立的搜索路径，互相交叉验证：

两条路用的是完全不同的索引（Tavily/Firecrawl vs Google），所以适合对关键事实做双路交叉验证。除此之外还有网页抓取 / 站点扫描 / 信源回查 / 配置诊断工具。

为什么不直接用 Claude Code 自带的 WebSearch / WebFetch？

• 自带工具受后端策略限制，部分地区不可用、命中率不稳定

• 自带工具不会把搜索结果显式喂给模型，Claude 经常仍走内部记忆，幻觉率高

• 没有结构化信源回传，难以追溯

本项目把这三件事都修好了，且主模型走火山方舟 Ark（国内直连、无需代理），Tavily/Firecrawl/Gemini 走代理。

Related MCP server: web-search-agent

工作原理

你 → Claude Code → multsearch MCP → ┬─ Tavily + Firecrawl 找源 ──► LLM summarize   (web_search, Path A)
                                    ├─ Gemini + Google grounding                   (gemini_search, Path B)
                                    ├─ Tavily extract / Firecrawl scrape           (web_fetch)
                                    └─ Tavily map                                  (web_map)

web_search 的文本模式流程：Tavily + Firecrawl 并行抓信源 → 组装成编号信源文本 → 喂给 LLM（glm-5.2）让它只依据信源作答，每条事实带 [n] 引用。模型本身不联网，所以不会幻觉编造。信源以 Tavily/Firecrawl 的实际结果为准，模型若附了信源列表会被剥离。

gemini_search 走 Gemini 原生 Google Search grounding，返回 grounded 答案 + Google 引用，遇 429/5xx 指数退避重试。

30 秒上手

两种安装方式：A. 让 Claude Code 自己配（推荐）/ B. 交互式向导。

A. Claude Code 驱动（非交互模式，推荐）

把这一段直接发给 Claude Code：

我本地有 multsearch-mcp 源码（路径：<填绝对路径>），请把它安装到我当前项目里（scope=project）。 你需要先 cd 到我当前项目目录，然后通过下面这条命令完成安装。我会告诉你我的 Ark API Key（ark-... 开头），Tavily / Firecrawl / Gemini 都跳过：

uvx --from '<源码路径>[setup]' \
    multsearch-setup \
    --non-interactive \
    --package-spec <源码路径> \
    --scope project \
    --provider ark \
    --api-key <我会粘贴的 Ark Key>

装完检查 .mcp.json 是否只在当前目录、claude mcp list 是否能看到 multsearch。

B. 交互式向导（自己跑）

cd ~/your-project          # ← 关键：决定 .mcp.json 写到哪里
uvx --from '<源码路径>[setup]' multsearch-setup --package-spec <源码路径>

向导会一步步问 LLM 服务来源（Ark / 自定义）、API Key、Tavily / Firecrawl / Gemini（均可选）、作用域，全程键盘选项 + 回车，不需要手写任何配置文件。完成后自动跑 claude mcp add-json 注册到当前项目 .mcp.json。重启 Claude Code 后 /mcp 能看到 multsearch。

没装 uv？curl -LsSf https://astral.sh/uv/install.sh | sh 然后重开终端。

API Key 申请指南

主 LLM Key 必需，其余可选。最佳零成本组合 = Ark + Tavily + Gemini，三家都有免费额度，全程不用绑卡。

1. 火山方舟 Ark（主 LLM，必需）

Ark 走国内直连，Tavily / Firecrawl / Gemini 走代理。

2. Tavily（强烈建议，可选）

不配 Tavily：web_search 退化为只用 Firecrawl 一路；web_fetch / web_map 不可用。

3. Firecrawl（可选）

4. Gemini（可选 · 第二路搜索）

工作原理（配置形态）

向导跑完后，项目根目录的 .mcp.json 大致长这样（敏感字段已脱敏）：

{
  "mcpServers": {
    "multsearch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "<源码路径>", "multsearch"],
      "env": {
        "MULT_PROVIDER": "custom",
        "MULT_API_URL": "https://ark.cn-beijing.volces.com/api/plan/v3",
        "MULT_API_KEY": "ark-****",
        "MULT_MODEL": "glm-5.2",
        "MULT_MAX_TOKENS": "8192",
        "TAVILY_API_KEY": "tvly-****",
        "FIRECRAWL_API_KEY": "fc-****",
        "GEMINI_API_KEY": "****",
        "GEMINI_MODEL": "gemini-2.5-flash",
        "HTTP_PROXY": "http://127.0.0.1:7890",
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "NO_PROXY": "localhost,127.0.0.1,ark.cn-beijing.volces.com,*.volces.com"
      }
    }
  }
}

Claude Code 启动时读这个文件，按 stdio 协议拉起一个 Python 进程（本项目），通过 MCP 协议转发工具调用。httpx 默认 trust_env=True，会读 HTTP_PROXY / NO_PROXY，所以 Tavily/Firecrawl/Gemini 走代理、Ark 走直连。

作用域怎么选

向导第 6 步选作用域：

新手选 project，把 .mcp.json 提交进 git 即可。

进阶配置

切换 Provider / 模型

向导第 2 步可选 Ark / 自定义。已装好想改：重新跑向导，或直接编辑 .mcp.json 的 env 段。运行时也可用 switch_model 工具切换模型并持久化到 ~/.config/multsearch/config.json。

完整环境变量参考

配置优先级：环境变量 > ~/.config/multsearch/config.json。

验证安装

claude mcp list
# 应该出现一行：multsearch    connected

在 Claude Code 里新开会话：

用 multsearch 的 web_search 搜一下「AKShare stock_zh_a_spot_em 的 limit 参数默认返回多少只」，把信源列出来。

连通后会看到 Claude 调用 web_search，输出带 [编号] 引用的回答。再用 get_sources 取回完整信源列表。

第二路：

用 multsearch 的 gemini_search 搜同一个问题，对比两路结果。

常见问题

Q：/mcp 看不到 multsearch？ A：99% 是 Claude Code 没重启。先 claude mcp list 看命令行是否能看到，能看到就完全重启 Claude Code（退出再开，不是新会话）。

Q：改了源码不生效？ A：uv tool run --from <path> 会缓存构建的 wheel。改源码后bump pyproject.toml 的 version（强制重建 wheel），或清 uv 缓存（sdists-v9/path + archive-v0 下本包目录），再 /mcp 重连。

Q：web_search 返回空 content？ A：多半是 Tavily/Firecrawl 没连上（代理没开 → HTTP 000）。代码里 except Exception: return None 静默兜底了。开代理（Clash 127.0.0.1:7890），用 get_config_info 测连通性，或用 dangerouslyDisableSandbox 的 curl 直连 api.tavily.com 排查。

Q：gemini_search 报失败？ A：Google API 必须走代理（不在 NO_PROXY 里），且 GEMINI_API_KEY 要设置。免费档 15 RPM，并发下可能 429，已内置退避重试。

Q：能用其它 OpenAI 兼容端点吗？ A：可以。MULT_PROVIDER=custom + 自填 MULT_API_URL / MULT_MODEL 即可（如 DeepSeek、智谱、内网网关等）。

Q：为什么删掉了 plan_ 规划工具？* A：早期版本有一套 6 阶段搜索规划状态机，实际使用中调用方很少走，维护成本高，已移除以聚焦双路搜索内核。web_search 现在是直接的找源 → 总结流程，带同 query+model 的 LRU 响应缓存。