multsearch-mcp
multsearch-mcp is a local MCP server for Claude Code that performs real web searches with two independent search paradigms and explicit source return.
web_search— Path A: runs Tavily + Firecrawl + SearXNG in parallel to gather sources, then an LLM (default GLM-5.2 via Volcengine Ark) synthesizes a cited answer with[n]inline references; returns asession_id,sources_count, and cache status. Optional per-requestmodelandextra_sourcesquota.gemini_search— Path B: native Google Search grounding via Gemini 2.5 Flash, giving a grounded answer plus Google citations from an entirely different index (for cross-validation).get_sources— retrieves the full source list for a previousweb_searchsession using itssession_id.web_fetch— fetches a URL and converts it to structured, full-fidelity Markdown (Tavily extract with Firecrawl fallback).web_map— crawls a site graph to list discoverable URLs, with controls formax_depth,max_breadth,limit,timeout, and natural-languageinstructionsfiltering.get_config_info— shows current configuration, tests API connectivity via the/modelsendpoint, and lists available models (keys masked).switch_model— changes the default LLM model for subsequent operations and persists it to~/.config/multsearch/config.json.
Integrates with Google Search via the Gemini API to perform grounded searches (Path B), providing answers with citations from Google's index for cross-verification of search results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@multsearch-mcp search for 'machine learning trends 2025' and cross-validate"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
multsearch-mcp
Claude Code 多路联网搜索 MCP
两套搜索范式交叉验证 · 信源显式回传 · 国内可用
这是什么
一个为 Claude Code 设计的本地 MCP 服务器。装上之后,Claude 回答前会真的去网上查,并把信源显式带回来,而不是凭印象瞎答。
核心是两套搜索范式,互相交叉验证:
范式 | 工具 | 信源 | 模型 |
Path A · 信源聚合 |
| Tavily + Firecrawl + SearXNG 三路并行找源 | LLM 基于信源 summarize(默认火山方舟 Ark |
Path B · 原生 grounding |
| Google Search grounding | Gemini 2.5 Flash |
两套范式用的是完全不同的索引(Tavily / Firecrawl / SearXNG vs Google),适合对关键事实做交叉验证。除此之外还有网页抓取、站点扫描、信源回查、配置诊断等辅助工具。
Related MCP server: fast-webfetch-mcp
提供的工具
工具 | 作用 |
| Tavily + Firecrawl + SearXNG 并行找源 → LLM 综合成带 |
| Gemini + Google grounding 直接给 grounded 答案 + Google 引用(Path B) |
| 用 |
| 抓任意网页转结构化 Markdown(Tavily extract → Firecrawl 兜底) |
| 扫描一个站点,列出全部可访问 URL |
| 查看当前配置 + 测试 API 连通性 + 列出可用模型 |
| 切换默认 LLM 模型并持久化到 |
为什么不直接用 Claude Code 自带的 WebSearch / WebFetch?
自带工具受后端策略限制,部分地区不可用、命中率不稳定
自带工具不会把搜索结果显式喂给模型,Claude 经常仍走内部记忆,幻觉率高
没有结构化信源回传,难以追溯
本项目把这三件事都修好了,且主模型走火山方舟 Ark(国内直连、无需代理),Tavily / Firecrawl / Gemini 走代理,SearXNG 默认直连。
工作原理
你 → Claude Code → multsearch MCP → ┬─ Tavily + Firecrawl + SearXNG 找源 ─► 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 + SearXNG 并行抓信源 → 组装成编号信源文本 → 喂给 LLM(glm-5.2)让它只依据信源作答,每条事实带 [n] 引用。模型本身不联网,所以不会幻觉编造。信源以 Tavily / Firecrawl / SearXNG 的实际结果为准,模型若附了信源列表会被剥离。同 query + model 的响应走 LRU 缓存直接命中。
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 都跳过(SearXNG 默认就启用,无需配置):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,三家都有免费额度,全程不用绑卡。SearXNG 默认免费开启、无需 key,作为 web_search 第三路信源。
1. 火山方舟 Ark(主 LLM,必需)
项 | 说明 |
控制台 | |
Key 前缀 |
|
模型 |
|
计费 | 按 token,有免费 / 体验额度 |
Ark 走国内直连,Tavily / Firecrawl / Gemini 走代理。
2. Tavily(强烈建议,可选)
项 | 说明 |
注册 | |
免费额度 | 1,000 次 / 月,无需绑卡 |
用途 |
|
不配 Tavily:web_search 退化为 Firecrawl + SearXNG 两路;web_fetch / web_map 不可用。
3. Firecrawl(可选)
项 | 说明 |
注册 | |
免费额度 | 1,000 credits / 月,无需绑卡 |
用途 |
|
4. Gemini(可选 · 第二路搜索)
项 | 说明 |
取 Key | |
用途 |
|
注意 | Google API 在中国大陆需走代理( |
5. SearXNG(可选 · 第三路信源)
项 | 说明 |
是什么 | 自建 / 公开的元搜索引擎,聚合 Google / Bing / DuckDuckGo 等多引擎结果 |
默认地址 |
|
用途 |
|
Key | 无需 API Key |
引擎 |
|
代理 | 代码内 |
注意 | 实例需在 |
配置文件形态
向导跑完后,项目根目录的 .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 走直连;SearXNG 单独用 trust_env=False 直连。
作用域怎么选
向导第 6 步选作用域:
Scope | 配置文件位置 | 谁能看到 | 推荐场景 |
project |
| 入 git 后团队共享 | 默认 |
user |
| 本机所有项目 | 一台机器多项目都用 |
local |
| 仅本机本项目 | 个人调试 |
新手选 project,把 .mcp.json 提交进 git 即可。
进阶配置
切换 Provider / 模型
向导第 2 步可选 Ark / 自定义。已装好想改:重新跑向导,或直接编辑 .mcp.json 的 env 段。运行时也可用 switch_model 工具切换模型并持久化到 ~/.config/multsearch/config.json。
完整环境变量参考
变量 | 默认值 | 说明 |
|
|
|
| — | OpenAI 兼容端点(Ark: |
| — | 必需 |
|
| LLM 模型,可用 |
| — | 推理模型建议 |
|
| LLM 流式请求的最大重试次数 |
|
| 指数退避 multiplier |
|
| 单次重试最大等待秒数 |
| — | 可选, |
|
| Tavily API 入口 |
|
| 关闭则跳过 Tavily 找源 |
| — | 可选, |
|
| Firecrawl API 入口 |
| — | 可选, |
|
| Gemini 模型 |
|
| Gemini API 入口 |
|
| SearXNG 实例地址(第三路信源) |
|
| 逗号分隔的引擎列表 |
|
| 关闭则不采集 SearXNG 信源 |
| — | 中国大陆访问 Tavily / Firecrawl / Gemini 需代理(SearXNG 直连不受影响) |
| — | 国内 API( |
|
| 详细日志 |
|
|
|
|
| 日志输出目录 |
配置优先级:环境变量 > ~/.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 搜同一个问题,对比两路结果。
开发与测试
# 安装开发依赖
uv sync --extra dev
# 跑纯函数单测(不依赖网络)
pytest tests/test_text_mode.py 是端到端活链路验证脚本:Tavily / Firecrawl 并行找源 → LLM summarize,需要先准备好 MULT_API_KEY / TAVILY_API_KEY / FIRECRAWL_API_KEY。
常见问题
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 静默兜底了;SearXNG 默认开启会兜底一路信源(走直连),若三路全空再开代理(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:为什么没有规划 / 任务拆解类工具?
A:早期版本有一套 6 阶段搜索规划状态机,实际使用中调用方很少走,维护成本高,已移除以聚焦两套搜索范式(Path A 多源聚合 + Path B Gemini grounding)。web_search 现在是直接的「找源 → 总结」流程,带同 query + model 的 LRU 响应缓存。
Available Tools
7 toolsgemini_searchA
Performs a web search via Gemini + Google Search grounding (Google's index).
Independent of Tavily/Firecrawl — use as a second search path for cross-validation.
Returns the grounded answer plus Google-sourced citations.
Requires GEMINI_API_KEY (get a free key at https://aistudio.google.com/apikey).
Inputs: query (required). Returns: object
get_config_infoA
Returns current multsearch MCP server configuration and tests API connectivity.
**Key Features:**
- **Configuration Check:** Verifies environment variables and current settings.
- **Connection Test:** Sends request to /models endpoint to validate API access.
- **Model Discovery:** Lists all available models from the API.
**Edge Cases & Best Practices:**
- Use this tool first when debugging connection or configuration issues.
- API keys are automatically masked for security in the response.
- Connection test timeout is 10 seconds; network issues may cause delays.
Inputs: no named parameters.
get_sourcesB
When you feel confused or curious about the search response content, use the session_id returned by web_search to invoke the this tool to obtain the corresponding list of information sources.
Retrieve all cached sources for a previous web_search call.
Provide the session_id returned by web_search to get the full source list.
Inputs: session_id (required). Returns: object
switch_modelA
Switches the default LLM model used for search and fetch operations, persisting the setting.
**Key Features:**
- **Model Selection:** Change the AI model for web search synthesis and content fetching.
- **Persistent Storage:** Model preference saved to ~/.config/multsearch/config.json.
- **Immediate Effect:** New model used for all subsequent operations.
**Edge Cases & Best Practices:**
- Use get_config_info to verify available models before switching.
- Invalid model IDs may cause API errors in subsequent requests.
- Model changes persist across sessions until explicitly changed again.
Inputs: model (required).
web_fetchA
Fetches and extracts complete content from a URL, returning it as a structured Markdown document.
**Key Features:**
- **Full Content Extraction:** Retrieves and parses all meaningful content (text, images, links, tables, code blocks).
- **Markdown Conversion:** Converts HTML structure to well-formatted Markdown with preserved hierarchy.
- **Content Fidelity:** Maintains 100% content fidelity without summarization or modification.
**Edge Cases & Best Practices:**
- Ensure URL is complete and accessible (not behind authentication or paywalls).
- May not capture dynamically loaded content requiring JavaScript execution.
- Large pages may take longer to process; consider timeout implications.
Inputs: url (required).
web_mapA
Maps a website's structure by traversing it like a graph, discovering URLs and generating a comprehensive site map.
**Key Features:**
- **Graph Traversal:** Explores website structure starting from root URL.
- **Depth & Breadth Control:** Configure traversal limits to balance coverage and performance.
- **Instruction Filtering:** Use natural language to focus crawler on specific content types.
**Edge Cases & Best Practices:**
- Start with low max_depth (1-2) for initial exploration, increase if needed.
- Use instructions to filter for specific content (e.g., "only documentation pages").
- Large sites may hit timeout limits; adjust timeout and limit parameters accordingly.
Inputs: url (required), limit, timeout, max_depth, +2 more. Returns: result
web_searchA
Performs a deep web search: Tavily + Firecrawl find sources, then the LLM (default GLM-5.2 via Ark) synthesizes a cited answer.
Returns:
- session_id string pass to get_sources to retrieve full source list
- content string LLM's source-based answer (with [n] inline citations)
- sources_count int
- cached bool true if response was served from in-memory result cache
Inputs: query (required), model, extra_sources.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose: configuration, search (two providers), source retrieval, URL fetch, site mapping, and model switching. The two search tools (web_search and gemini_search) overlap in function but descriptions clearly position gemini_search as a cross-validation path, so an agent can disambiguate. Overall boundaries are clear.
Naming mixes verb-first and object-first conventions: get_config_info/get_sources/switch_model are verb_noun, while web_search/web_fetch/web_map/gemini_search are object_verb (or proper-noun_verb). This inconsistency is noticeable but all names are readable and lower_snake_case, so it is not chaotic.
Seven tools is well within the ideal 3–15 range. Each tool covers a distinct capability (config, search, sources, fetch, map, model switch) and none seem redundant or filler.
The surface covers the full workflow: search via two providers, retrieve sources via session_id, fetch single URLs, map website structures, and manage configuration/model. There are no obvious dead ends; the only minor gap might be a way to clear cache, but that is not essential to the core search/fetch/map domain.
Maintenance
Related MCP Connectors
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Web search and clean-text fetch MCP server (Tavily-powered, SSRF-guarded).
Web search API and MCP server for developers building AI agents.
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables Claude to perform web searches using Perplexity's API with intelligent model selection based on query intent and support for domain and recency filtering.64MIT
- AlicenseNot gradedqualityDmaintenanceA high-performance MCP server for web fetching in Claude Code using Firecrawl backend with automatic fallback.2MIT
- AlicenseAqualityCmaintenanceMCP server for web page fetching (converting to Markdown/text with automatic fallback between Tavily and Firecrawl) and web search via Tavily.2MIT
- AlicenseBqualityDmaintenanceMCP server for Claude Code that provides Google text search, web content extraction, and image search with dual-platform (Google Images + Pinterest) and AI visual analysis with quality scoring.5MIT