内容
# deepseek-mcp
[](LICENSE)
[](pyproject.toml)
[](https://github.com/arizen-dev/deepseek-mcp/actions/workflows/test.yml)
使用 DeepSeek 作为 Claude Code、Codex 或任何 MCP 兼容客户端的小型、廉价的监督工作器。
`deepseek-mcp` 是一个 tiny stdio MCP 服务器，包含两个工具：
```text
deepseek(提示, 系统?) — 快速、廉价、不思考（闪存）
advise(提示, 系统?, 努力?) — 深度推理（专业 + 思考）
```
它适用于边界任务，其中另一个模型可以减少机械负载：
- 分类 inbox、tickets、logs、notes 或 docs；
- 总结数据包；
- 将杂乱的文本转换为 JSON 或表格；
- 填充模板；
- 生成第一版机械编辑；
- 为人类或主要代理生成可审查的候选输出。
它不适用于自主架构、安全策略、最终客户端散文或需要判断的决策。
## 快速开始
### 1. 安装
使用 `uvx` 零安装：
```bash
DEEPSEEK_API_KEY="sk-..." uvx deepseek-mcp-server
```
或永久安装：
```bash
pip install "git+https://github.com/arizen-dev/deepseek-mcp.git"
```
或克隆并本地安装：
```bash
git clone https://github.com/arizen-dev/deepseek-mcp.git
cd deepseek-mcp
pip install -e .
```
### 2. 添加您的 DeepSeek 密钥
在以下位置创建 API 密钥：
```text
https://platform.deepseek.com/api_keys
```
然后导出它：
```bash
export DEEPSEEK_API_KEY="sk-..."
```
对于 Claude Code，设置最低摩擦的方法是将密钥放在全局设置中：
```json
{
"env": {
"DEEPSEEK_API_KEY": "sk-..."
}
}
```
路径：
```text
~/.claude/settings.json
```
MCP 服务器在客户端启动时启动，因此在更改环境变量/配置后重启 Claude Code 或 Codex。
### 3. 配置 MCP
如果您通过 pip（或 uvx）安装，请直接使用已安装的命令：
```json
{
"mcpServers": {
"deepseek": {
"command": "deepseek-mcp-server",
"args": [],
"env": {
"DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}"
}
}
}
}
```
如果您克隆了仓库，请直接指向脚本：
```json
{
"mcpServers": {
"deepseek": {
"command": "python3",
"args": ["/absolute/path/to/deepseek-mcp/deepseek_mcp_server.py"],
"env": {
"DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}"
}
}
}
}
```
重启后，`/mcp` 应该显示一个 `deepseek` 服务器。
在 Claude Code 中，工具名称为：
```text
mcp__deepseek__deepseek — 闪存（快速、机械）
mcp__deepseek__advise — 专业（深度推理）
```
## Codex
对于 Codex，在 `~/.codex/config.toml` 中添加一个全局 MCP 服务器：
```toml
[mcp_servers.deepseekWorker]
command = "deepseek-mcp-server"
args = []
[mcp_servers.deepseekWorker.env]
DEEPSEEK_API_KEY = "sk-..."
```
Codex TOML 不会像 Claude 项目 MCP 配置文件那样扩展 `"${DEEPSEEK_API_KEY}"`。将密钥直接放在 TOML 环境块中，或使用 Codex 环境支持的任何秘密机制。
## 演示
提示：
```text
将这些文件分类为 doc / code / config。仅返回 JSON：
- README.md
- pyproject.toml
- src/deepseek_mcp/server.py
```
示例输出：
```json
[
{"file": "README.md", "type": "doc"},
{"file": "pyproject.toml", "type": "config"},
{"file": "src/deepseek_mcp/server.py", "type": "code"}
]
```
服务器追加轻量级元数据：
```text
---
_deepseek · model=deepseek-v4-flash latency=18.42s tokens=52+74 cost=$0.0001_
```
延迟 heavily 取决于提示大小、模型、网络和 API 负载。将基准测试视为方向性，而不是保证。
## CLI
安装后，您可以使用 CLI 进行烟雾测试和一次性调用：
```bash
# 验证设置
python -m deepseek_mcp check
# 一次性闪存调用
python -m deepseek_mcp run "分类：紧急 / 稍后 — '生产环境服务器宕机'"
# 顾问调用，深度推理
python -m deepseek_mcp advise "我们应该构建还是购买分析工具？" --effort max
```
退出代码：0 = 成功，1 = API 错误，2 = 缺少密钥。
## 模型
| 工具 | 模型 | 模式 | 最适合 |
|------|-------|------|----------|
| `deepseek` | deepseek-v4-flash | 非思考 | 分类、提取、格式化、机械编辑 |
| `advise` | deepseek-v4-pro | 思考（努力：中等/高/最大） | 架构、权衡、第二意见、模糊性 |
## 成本
每次调用的成本取决于令牌数量和模型。定价参考 [api.deepseek.com](https://api.deepseek.com) （截至 2026-04-30）。
| 模型 | 输入（丢失） | 输入（缓存命中） | 输出 |
|-------|-------------|-------------------|--------|
| `deepseek-v4-flash` | $0.14/1M | $0.0028/1M | $0.28/1M |
| `deepseek-v4-pro` | $0.435/1M¹ | $0.0036/1M¹ | $0.87/1M¹ |
¹ 专业定价截至 2026-05-31 享有 75% 折扣。非折扣价：$1.74/$0.0145/$3.48。
**典型每次调用成本（缓存未命中）：**
| 任务 | 闪存 | 专业 |
|------|-------|-----|
| 小型（~1K 输入 + ~0.5K 输出） | ~$0.0003 | ~$0.0009 |
| 中型（~4K 输入 + ~2K 输出） | ~$0.001 | ~$0.003 |
每个响应页脚包含根据令牌使用情况估计的 `cost=$...`。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DEEPSEEK_API_KEY` | — | 必需。您的 DeepSeek API 密钥。 |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基本 URL（更改为代理/兼容提供商）。 |
| `DEEPSEEK_MCP_LOG` | （未设置） | 设置为 `1` 以将调用元数据记录到 `~/.deepseek-mcp/calls.jsonl`（不记录提示）。 |
## 何时使用
良好：
- "分类这 200 个文件名。标记不确定性。"
- "将这个粗糙的笔记转换为 CSV 表格。"
- "提取所有 TODO 并按所有者分组。"
- "从这个杂乱的列表中创建候选 JSON。使用 null 表示缺失的值。"
- "总结此数据包以供审查；不要做出决定。"
糟糕：
- "设计我的架构。"
- "编写最终的客户端电子邮件。"
- "决定这是否安全。"
- "解决这个模糊的业务规则。"
- "直接发布此回复。"
像使用快速的初级分析师一样使用它，您将审查其工作，而不是作为所有者。
## 工作原理
服务器：
1. 从标准输入读取 JSON-RPC 消息；
2. 暴露两个 MCP 工具：`deepseek`（闪存，非思考）和 `advise`（专业，思考）；
3. 将您的提示发送到 DeepSeek 的 OpenAI 兼容聊天完成 API；
4. 流式传输响应；
5. 返回文本以及模型、延迟、令牌和成本元数据。
没有数据库，没有后台守护进程，没有本地 Web 服务器，也没有文件系统访问权限，除了 MCP 客户端启动进程。
## 烟雾测试
安装后：
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| DEEPSEEK_API_KEY="sk-..." deepseek-mcp-server
```
您应该会看到包含两个工具（`deepseek` + `advise`）的 JSON 响应。
然后测试一个真正的调用：
```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call",\
"params":{"name":"deepseek","arguments":{"prompt":"Return exactly: ok"}}}' \
| DEEPSEEK_API_KEY="sk-..." deepseek-mcp-server
```
## 示例
查看 [examples/](examples/) 中的真实提示模板：
- [flash_classify.md](examples/flash_classify.md) — inbox 分类
- [advise_architecture.md](examples/advise_architecture.md) — 架构决策
- [advise_tradeoff.md](examples/advise_tradeoff.md) — 构建 vs 购买
## 基准测试
查看 [docs/benchmark.md](docs/benchmark.md) 以获取验证观察和用法指导。
## 开发
```bash
pip install -e ".[dev]"
pip install -r requirements-dev.txt # 替代方案
python -m pytest
```
## 兼容端点
`deepseek-mcp` 与任何 OpenAI 兼容的 API 配合使用。将 `DEEPSEEK_BASE_URL` 指向其他地方：
| 提供商 | `DEEPSEEK_BASE_URL` | 备注 |
|----------|---------------------|-------|
| DeepSeek | `https://api.deepseek.com` | 默认 |
| Google Gemini | `https://generativelanguage.googleapis.com/v1beta/openai/` | 需要 Gemini API 密钥；模型如 `gemini-2.5-flash` |
| Ollama（本地） | `http://localhost:11434/v1` | 运行任何本地模型；例如 `llama3`、`qwen2.5` |
| vLLM（自托管） | `http://localhost:8000/v1` | 用于自托管开放权重模型 |
| Mistral API | `https://api.mistral.ai/v1` | 需要 Mistral API 密钥 |
## 安全注意事项
- 工作器仅返回文本。它无法调用工具、写入文件或访问您的仓库。输出位于主模型的上下文中 — 您审查后才使用。
- 不要提交 API 密钥。
- 优先使用客户端/全局环境变量注入，而不是在项目仓库中硬编码密钥。
- 将模型输出视为不受信任的候选文本。
- 不要让工具访问您不会直接粘贴到 DeepSeek 中的机密。
- 在输出到达用户、客户、生产系统或公共渠道之前审查。
## 许可证
MIT
