<div align="center">

multsearch-mcp

Claude Code 双路联网搜索 MCP

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

</div>

---

这是什么

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

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

路径	工具	索引来源	模型
Path A	web_search	Tavily + Firecrawl 找源	LLM 基于信源 summarize（默认火山方舟 Ark glm-5.2）
Path B	gemini_search	Google Search grounding	Gemini 2.5 Flash

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

工具	它干什么
web_search	Tavily + Firecrawl 并行找源 → LLM 综合成带 [编号] 内联引用的答案（Path A）
gemini_search	Gemini + Google grounding 直接给 grounded 答案 + Google 引用（Path B）
get_sources	用 web_search / gemini_search 返回的 session_id 取回完整信源列表
web_fetch	抓任意网页转结构化 Markdown（Tavily extract → Firecrawl 兜底）
web_map	扫描一个站点，列出全部可访问 URL
get_config_info	查看当前配置 + 测试 API 连通性 + 列出可用模型
switch_model	切换默认 LLM 模型并持久化

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

• 自带工具受后端策略限制，部分地区不可用、命中率不稳定
• 自带工具不会把搜索结果显式喂给模型，Claude 经常仍走内部记忆，幻觉率高
• 没有结构化信源回传，难以追溯

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

---

工作原理

你 → 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，必需）

项	说明
控制台	https://console.volcengine.com/ark
Key 前缀	ark-...
模型	glm-5.2（纯文本，国内直连无需代理）
计费	按 token，有免费 / 体验额度

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

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

项	说明
注册	https://app.tavily.com/home
免费额度	1,000 次 / 月，无需绑卡
用途	web_search 找源 + web_fetch / web_map

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

3. Firecrawl（可选）

项	说明
注册	https://www.firecrawl.dev/signin?view=signup
免费额度	1,000 credits / 月，无需绑卡
用途	web_search 找源 + web_fetch 兜底

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

项	说明
取 Key	https://aistudio.google.com/apikey（免费）
用途	gemini_search 独立 Google 索引交叉验证
注意	Google API 在中国大陆需走代理（HTTP_PROXY / HTTPS_PROXY）

---

工作原理（配置形态）

向导跑完后，项目根目录的 .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 步选作用域：

Scope	配置文件位置	谁能看到	推荐场景
project	<项目>/.mcp.json	入 git 后团队共享	默认
user	~/.claude.json	本机所有项目	一台机器多项目都用
local	<项目>/.claude/settings.local.json	仅本机本项目	个人调试

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

---

进阶配置

切换 Provider / 模型

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

完整环境变量参考

变量	默认值	说明
MULT_PROVIDER	custom	custom / ark（向导预设）
MULT_API_URL	—	OpenAI 兼容端点（Ark: https://ark.cn-beijing.volces.com/api/plan/v3）
MULT_API_KEY	—	必需
MULT_MODEL	glm-5.2	LLM 模型，可用 switch_model 切换
MULT_MAX_TOKENS	—	推理模型建议 8192（reasoning 要吃 token）
TAVILY_API_KEY	—	可选，web_search 找源 + web_fetch / web_map
FIRECRAWL_API_KEY	—	可选，web_search 找源 + web_fetch 兜底
GEMINI_API_KEY	—	可选，gemini_search 第二路
GEMINI_MODEL	gemini-2.5-flash	Gemini 模型
HTTP_PROXY / HTTPS_PROXY	—	中国大陆访问 Tavily/Firecrawl/Gemini 需代理
NO_PROXY	—	国内 API（ark.cn-beijing.volces.com 等）直连
MULT_DEBUG	false	详细日志
MULT_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR
MULT_LOG_DIR	~/.config/multsearch/logs	日志输出目录

配置优先级：环境变量 > ~/.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 响应缓存。