Skip to main content
Glama
DeepSeek Search MCP

DeepSeek Search MCP

by ky-rgb

DeepSeek Search MCP

CI

把 DeepSeek 的 网页搜索与抓取接口 封装成标准 MCP (Model Context Protocol) Server,让 Claude Code、Claude Desktop、Cursor、Windsurf 等任何支持 stdio 的 agent 都能直接搜索网页、抓取网页正文。

  • deepseek_search — 调用 POST /v1/tools/search,返回带排序分数的结构化搜索结果

  • deepseek_fetch — 调用 POST /v1/tools/fetch,把单个网页抓成干净 Markdown

English: A community MCP server exposing DeepSeek's Web Search & Web Fetch APIs as deepseek_search / deepseek_fetch tools for any stdio-capable agent. Not affiliated with DeepSeek.

特性

  • 完整覆盖官方参数:query / count(1–50)/ need_content / ori_question / localization

  • 面向 agent 设计:工具描述里内置搜索语法(site:、lang:、after: 等)、计费说明和选型建议,模型不需要额外提示就知道怎么用

  • 自动重试:408 / 429 / 5xx / 网络错误按指数退避重试(默认 2 次),支持数字或 HTTP 日期格式的 Retry-After;其余 4xx 不重试

  • 错误可读:把 DeepSeek 的 OpenAI 兼容错误格式翻译成带 HTTP 状态码、原始 message 和处理建议的文本

  • URL 安全校验:拒绝带凭据、空白/控制字符、非法端口,以及指向 localhost、私有网段、链路本地、组播或保留地址的 URL

  • 内容截断保护:deepseek_fetch 默认最多返回 10 万字符(可用 max_chars 调整,0 表示不限),避免一次抓取把上下文撑爆

  • 只读安全:两个工具都标记了 readOnlyHint / idempotentHint;API Key 只从环境变量读取,不写进任何文件

Related MCP server: tinyfish-web-mcp

工具

参数

类型

必填

默认

说明

query

string

是

—

搜索词,1–128 字符,支持搜索语法

count

integer

否

10

返回条数,1–50

need_content

boolean

否

false

是否在每条结果的 content 中返回网页正文

ori_question

string

否

—

触发搜索的原始问题(1–128 字符),帮助理解意图

localization

string

否

—

用于优先返回本地化结果的 IP 地址

每条结果包含:rerank_score(0–3,≥1.5 为优质)、title、url、snippet(~100–200 字符,适合展示)、summary(~600–800 字符,适合给模型读)、content(正文,需 need_content=true)、site_name、site_icon、date、authority(0–4,≥3 为极权威)。

搜索语法(由搜索引擎原样处理,可组合):

操作符

示例

site:

DeepSeek site:github.com OR site:huggingface.co

-site:

DeepSeek -site:example.com

-

DeepSeek -广告

"..."

DeepSeek "精确短语"

-"..."

DeepSeek -"release notes"

lang:

DeepSeek lang:zh,en

after:

DeepSeek after:2025-01-01

before:

DeepSeek before:2026-06-01

deepseek_fetch

参数

类型

必填

默认

说明

url

string

是

—

http/https URL,需包含 host,不能带用户名密码、空白/控制字符或非法端口,不能指向本机/内网地址,≤8192 字符

max_chars

integer

否

100000

返回正文的最大字符数,0 为不限

返回:url、title、content(Markdown)、content_total_chars、truncated,被截断时附带 note。

安装与接入

前置条件:Python ≥ 3.10、uv、一个 DeepSeek API Key(开放平台 创建)。

方式一:uvx 直接运行(推荐)

不需要克隆仓库,uv 会自动从 GitHub 拉取并缓存本项目:

claude mcp add deepseek-search -s user -e DEEPSEEK_API_KEY=sk-你的key -- uvx --from git+https://github.com/ky-rgb/deepseek-search-mcp deepseek-search-mcp

-s user 表示注册到用户级,所有项目的会话都会自动启动它;不加的话默认是 local 作用域,只在运行命令时所在的项目目录生效。

方式二:克隆到本地

适合想改代码或离线使用的场景:

git clone https://github.com/ky-rgb/deepseek-search-mcp.git
cd deepseek-search-mcp
uv sync
claude mcp add deepseek-search -s user -e DEEPSEEK_API_KEY=sk-你的key -- uv --directory "$(pwd)" run deepseek-search-mcp

uv sync 会创建 .venv 并安装依赖;"$(pwd)" 在注册时展开为克隆目录的绝对路径并写入配置。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(Windows 为 %APPDATA%\Claude\claude_desktop_config.json),把 /path/to/... 替换成实际路径:

{
  "mcpServers": {
    "deepseek-search": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/deepseek-search-mcp",
        "run",
        "deepseek-search-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-你的key"
      }
    }
  }
}

保存后重启 Claude Desktop,工具列表里应能看到 deepseek_search 和 deepseek_fetch。

JSON 配置里必须写完整绝对路径:客户端直接拉起进程、不经过 shell,~ 和 $HOME 都不会展开。uv 的路径用 which uv 查(macOS 官方安装脚本默认在 ~/.local/bin/uv,Homebrew 在 /opt/homebrew/bin/uv,填展开后的完整路径)。

其他 stdio 客户端

所有支持 stdio 的 MCP 客户端都是同样的两要素:

  • 命令:uv --directory <克隆路径> run deepseek-search-mcp,或直接用虚拟环境入口 <克隆路径>/.venv/bin/deepseek-search-mcp(不依赖 PATH 中有 uv)

  • 环境变量:DEEPSEEK_API_KEY=sk-...

Server 使用 stdio 传输,日志只写 stderr,不会污染 JSON-RPC 通道。

环境变量

变量

必填

默认值

说明

DEEPSEEK_API_KEY

是

—

DeepSeek API Key(Bearer 鉴权)

DEEPSEEK_BASE_URL

否

https://api.deepseek.com

API 根地址(测试时可指向 mock 服务)

DEEPSEEK_TIMEOUT

否

60

单次请求超时(秒)

DEEPSEEK_MAX_RETRIES

否

2

可重试错误的额外重试次数(总尝试 = 重试次数 + 1)

DEEPSEEK_RETRY_BASE_DELAY

否

0.5

指数退避的基础延迟(秒)

DEEPSEEK_MAX_RETRY_DELAY

否

8

单次重试等待上限(秒),同时限制 Retry-After

错误处理

HTTP 状态

行为

400 / 401 / 402 / 403 / 404 / 413

直接报错,不重试;错误文本包含原始 message 和处理建议

408 / 429 / 5xx / 网络错误

指数退避自动重试;429 优先遵守 Retry-After 响应头

重试耗尽

返回最后一次错误,并注明尝试次数

典型错误提示示例:

DeepSeek fetch failed (HTTP 404): no usable content. No usable page content could be
retrieved: the URL is unavailable, the site blocks access, returns an error, uses an
unsupported content type, or the page has no extractable Markdown body. [code: not_found]

计费与限速

  • Search、Fetch 均按成功请求次数计费(5 元 / 1000 次),不按 token 或结果条数;失败、无结果、超时不计费。

  • count 不影响单次价格,所以一次取满(最多 50 条)比多次小请求更划算。

  • QPS 限制:Search 100、Fetch 25(账号级);Fetch 还有目标域名级限速,超限返回 429(会自动重试)。

  • Server 已把上述要点写进工具描述,agent 一般会自动选择更省钱的调用方式。

已知限制

  • deepseek_search 在 need_content=true 时没有输出长度上限:count 取满 50 且每条都带正文时,响应可能非常大,容易撑爆上下文。建议先用默认的 need_content=false 读 summary,确需全文时再对单页调用 deepseek_fetch(后者默认截断到 10 万字符,可用 max_chars 调整)。

开发与测试

uv sync
uv run pytest -q

测试是端到端的:tests/test_server.py 会起一个本地 mock DeepSeek API,通过真实的 stdio JSON-RPC 驱动 MCP server,覆盖:

  • 工具列表、输入 schema、只读/幂等注解

  • 搜索/抓取的请求体、请求头、路径

  • 可选参数省略、空结果提示

  • 错误映射(400 / 401 / 402 / 404 / 429 / 5xx)、重试与放弃逻辑

  • 本地参数校验(空白 query、非法/不安全 URL、count 越界、非法环境变量)不发出请求

  • Fetch 截断与 max_chars=0 不限长

  • 缺少/无效 API Key 的明确报错

  • 429 重试支持数字与 HTTP 日期两种 Retry-After

CI 在 GitHub Actions 上对 Python 3.10 / 3.12 / 3.14 跑同一套测试。

项目结构

deepseek-search-mcp/
├── pyproject.toml
├── uv.lock
├── LICENSE
├── README.md
├── .github/workflows/ci.yml
├── src/deepseek_search_mcp/
│   ├── __init__.py
│   ├── __main__.py        # python -m deepseek_search_mcp
│   ├── client.py          # DeepSeek HTTP 客户端:重试、错误解析、URL 校验
│   └── server.py          # FastMCP 工具定义与入口
└── tests/test_server.py   # 端到端测试(mock API + stdio MCP 客户端)

安全提示

  • 不要把 API Key 提交进 git 或写进 README;.gitignore 已忽略 .venv、缓存等。

  • 本 server 只做只读检索,不会修改任何远端状态。

  • 欢迎 issue / PR。

License

MIT © 2026 ky-rgb

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to search the live web and fetch URLs as clean Markdown, returning ranked search results and paginated page content through two lightweight tools.
      2
      23 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables any MCP-compatible AI agent to search the live web and fetch pages as clean Markdown, including batch fetching with rate limiting, retries, and context-safe truncation.
      3
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search the web through configured providers and crawl single pages or whole sites into clean Markdown or JSON, including content behind logins, over MCP STDIO or HTTP.
      -