Skip to main content
Glama
DeepSeek Search MCP

DeepSeek Search MCP

by ky-rgb
README.md
# DeepSeek Search MCP

[![CI](https://github.com/ky-rgb/deepseek-search-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ky-rgb/deepseek-search-mcp/actions/workflows/ci.yml)

把 DeepSeek 的 [网页搜索与抓取接口](https://api-docs.deepseek.com/zh-cn/guides/search) 封装成标准 **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 只从环境变量读取,不写进任何文件

## 工具

### `deepseek_search`

| 参数 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `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](https://docs.astral.sh/uv/)、一个 DeepSeek API Key([开放平台](https://platform.deepseek.com/) 创建)。

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

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

```bash
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 作用域,只在运行命令时所在的项目目录生效。

### 方式二:克隆到本地

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

```bash
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/...` 替换成实际路径:

```json
{
  "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` 响应头 |
| 重试耗尽 | 返回最后一次错误,并注明尝试次数 |

典型错误提示示例:

```text
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` 调整)。

## 开发与测试

```bash
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 跑同一套测试。

## 项目结构

```text
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](LICENSE) © 2026 ky-rgb