deepseek-search-mcp

基于 DeepSeek V4-Flash 原生联网搜索能力的高准确度搜索 MCP 服务器（Model Context Protocol Server）。

web_search 使用 DeepSeek Responses API 内置的 web_search 工具，由 V4-Flash 自动完成多轮搜索、来源核实与带引用答案合成；web_search_deep 进一步将问题拆解为多个子查询分别检索，再由 V4-Flash 交叉核验、综合成调研级答案。

• 单文件实现：核心服务仅一个 Python 文件，零第三方运行时依赖（纯 urllib + json 标准库）

• 协议自实现：手写 stdio 传输 + JSON-RPC 2.0，不依赖 MCP SDK，兼容 Claude Desktop / Codex / Cherry Studio / Hermes 等任何 MCP 客户端

• 无额外搜索 API：联网搜索能力由 DeepSeek API 原生提供，只需一个 DeepSeek API Key

目录

• 架构

• 功能特性

• 快速开始

• 工具说明

• 配置环境变量

• MCP 客户端接入

• 开发与测试

• 基准对比

• 已知限制

• 许可证

Related MCP server: Percival Deep Research

架构

纯文本 LLM（决策与提问）
    │  MCP 协议（stdio, JSON-RPC 2.0, Content-Length 帧）
    ▼
deepseek_web_search_mcp.py（单文件，零第三方依赖）
    │  DeepSeek Responses API（tools: web_search）
    ▼
DeepSeek V4-Flash（284B MoE，搜索 + 阅读 + 多轮核实 + 带来源引用合成）

设计参考了 GitHub 上主流 web search MCP 项目（mcp-brave-search、kindly-web-search-mcp-server）的"搜索引擎检索 + LLM 增强合成"模式，但搜索与合成均由 DeepSeek 原生完成，无需第三方搜索 API Key。

功能特性

web_search：模型自动规划多次搜索 → 阅读并核实来源 → 返回结构化、带来源链接的答案。

web_search_deep：先生成 3–6 个子查询（DEEPSEEK_DEEP_QUERIES 控制）分别检索（每个子查询独立搜索、独立来源）→ 由 V4-Flash 交叉核验 → 输出综合答案。实测能主动标注"来源冲突"与"信息不足"的存疑点。

快速开始

# 1. 设置 API Key（也可以直接在 MCP 客户端配置中注入）
export DEEPSEEK_API_KEY="sk-..."

# 2. 健康检查（验证 Key 与搜索链路）
python deepseek_web_search_mcp.py --health

# 3. 作为 MCP 服务器运行（stdio）
python deepseek_web_search_mcp.py

工具说明

web_search

• 参数：query（必填，string）— 要搜索的问题或主题，建议写成完整问题以提高相关性

• 返回：JSON，含 answer（带来源链接的综合答案）、sources（提取的引用 URL 列表）、elapsed_s、usage

web_search_deep

• 参数：query（必填，string）— 需要深度调研的问题，需具体、可拆解

• 返回：JSON，含 answer（交叉核验后的综合答案）、sub_queries（拆解出的子查询）、segments（每路子查询的检索结果）、sources、elapsed_s

health

• 参数：无

• 返回：status、模型/端点信息、搜索链路可用性、示例答案片段

配置环境变量

MCP 客户端接入

以 Claude Desktop 的 claude_desktop_config.json 为例：

{
  "mcpServers": {
    "deepseek-search": {
      "command": "python",
      "args": ["/absolute/path/to/deepseek_web_search_mcp.py"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DEEPSEEK_TIMEOUT_S": "180"
      }
    }
  }
}

其他支持 stdio 的 MCP 客户端（Codex、Cursor、Cherry Studio、Hermes 等）配置方式类似。

开发与测试

仓库内包含两套测试/对比工具：

完整测试用例、三方对比数据与发现的问题见 TESTING.md。

运行方式：

# stdio 全链路测试（--deep 附加深搜用例）
python test_stdio.py [--deep]

# 调用任意 stdio MCP 服务器（列出工具）
python mcp_client.py --cmd "npx.cmd" --args "-y tavily-mcp" --list --jsonl

# 三方对比（需 DEEPSEEK_API_KEY / TAVILY_API_KEY 环境变量）
python bench_search.py --deep "你的调研问题"

协议注意：tavily-mcp 等新版 MCP SDK 实现的服务器使用 NDJSON 行协议（每行一个 JSON），而本项目手写的服务器使用 Content-Length 帧协议（兼容 2024-11-05 / 2025-06-18 等协议版本的经典实现）。mcp_client.py 用 --jsonl 参数切换两种协议；initialize 请求对新版 SDK 服务器必须携带 capabilities 与 clientInfo 字段。

基准对比

实测（2026-08-09，DeepSeek V4-Flash 正式版）三方搜索能力对比：

要点：

• Tavily MCP 响应最快，但只做"检索不思考"：实测中把过时价格与官方价格并列返回而未甄别，准确性依赖使用方自行判断。

• web_search 返回带来源链接的综合答案，多轮搜索自动核实关键事实。

• web_search_deep 质量最高：交叉验证多来源，能主动指出"某信息系某媒体披露、官方未点名"等存疑点；代价是耗时明显更长。

结论：日常快查建议用 Tavily 或内置搜索；需要高准确度的调研与事实核查场景，建议使用 web_search_deep。

已知限制

1. 模型支持：DeepSeek Responses API 目前仅支持 deepseek-v4-flash，deepseek-v4-pro 尚不支持（官方计划 2026 年 8 月初加入）。

2. 响应提取：Responses API 的顶层 output_text 字段为空，正文需从 output[] 数组的 message.content[].output_text 中提取（本项目已处理）。

3. 耗时：联网搜索为多轮推理任务，单轮 30–180s、深搜 2–4 分钟，客户端侧超时需配置足够长。

4. notifications/initialized：该通知无响应，MCP 客户端不能同步等待（测试脚本中用线程 + 超时处理）。

许可证

MIT