DeepSeek MCP Server

DeepSeek MCP 服务

适用于 DeepSeek V4.1 Flash 和 V4 Pro API 的 MCP 服务：文本和视觉聊天、 Responses API、FIM 补全、Files API 生命周期操作、模型发现、 余额查询，以及有界内存对话。

1.4.0 版本使用稳定版 MCP TypeScript SDK v2，同时服务于 2026-07-28 协议和无状态旧版客户端。

当前动态

根据 2026 年 10 月 19 日的官方 API 文档核对：

• 规范的快速模型是 deepseek-flash，目前由 DeepSeek-V4.1-Flash-1017 提供服务。10 月 17 日的模型更新没有改变其 API 调用方式或模型 token 定价。
• deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 是 deepseek-flash 的临时别名。
• deepseek-v4-pro 继续提供 V4 Pro 0813。DeepSeek 撤回了其公布的 9 月路由调整计划；Pro 仍然可用，计费也未改变。
• V4.1 Flash 通过 Chat Completions 和 Responses 接受视觉输入。 V4 Pro 接受文本输入。使用 list_models 检查你账号的实时可用情况。
• Files API 支持上传、列出、检索和删除可重复使用的图像输入。
• DeepSeek 文档说明，deepseek-flash 的上下文窗口为 1M token，输出 token 数最多可达 384K。

这里的“多模态”指图像理解。此服务不生成图像、视频或音频。

工具

该服务提供十一种工具：

• chat_completion：文本或视觉 Chat Completions、思考控制、 函数工具、JSON 输出、流式聚合，以及可选的 conversation_id 记忆。
• create_response：无状态 Responses API 调用，支持文本/图像、推理 控制、函数工具、apply_patch 自定义工具、结构化输出，以及语义 流式聚合。
• completion：通过 /beta/completions 进行 FIM 补全。
• list_models：实时模型发现，包括显示名称、上下文/输出限制、输入/输出模态、推理强度等级和 API 能力。
• get_user_balance：账号可用情况和余额。
• upload_file：上传 base64 JPEG、PNG、GIF 或 WebP 数据，并获取可重复使用的 DeepSeek file_id。
• list_files：按游标、顺序和用途筛选条件列出已上传文件。
• retrieve_file：检索单个 file_id 的元数据。
• delete_file：删除单个已上传文件。
• reset_conversation：清除一个本地内存对话。
• list_conversations：列出本地内存对话 ID。

每种工具都声明 MCP 输出架构和行为注释。只有显式设置 include_raw_response=true，才会包含完整的提供方载荷。

API 行为

• 默认启用思考。标准推理力度为 none、 low、high 和 max。也接受兼容性别名：minimal 映射到 low；medium 和 xhigh 映射到 high；思考指南还接受 ultra 作为 max 的别名。
• Chat 的 stream_options 要求 stream=true。Chat 强制工具选择 （required 或命名函数）要求禁用思考。
• Chat 前缀补全（prefix=true）和严格函数工具 （strict=true）会自动使用 /beta/chat/completions。配置的 /v1 和 /beta 基础路径会针对 beta 请求进行规范化。
• 为兼容性，仍接受频率惩罚和存在惩罚，但 DeepSeek 会忽略它们。
• Responses 调用是无状态的：请发送完整输入历史。web_search 在服务端通过 deepseek-v4-pro 运行；DeepSeek 会在使用 deepseek-flash 时忽略它。 其他内置工具类型，例如 file_search、code_interpreter 和 mcp，均会被忽略。 支持的自定义工具为 { "type": "custom", "name": "apply_patch" }。返回的调用会出现在 custom_tool_calls 中；客户端负责执行这些调用并发送 custom_tool_call_output 历史记录。output_items 会保留完整返回的推理、消息和工具调用项目， 以便重放，而无需启用完整的原始提供方响应。
• FIM 处于 beta 阶段且不启用思考。它支持流式用量选项； echo=true 不能与 suffix 或 logprobs 同时使用。其指南说明输出限制为 4K，因此不要假设 Chat 的输出上限也适用。
• DEEPSEEK_REQUEST_TIMEOUT_MS 适用于整个请求，包括读取响应正文和流式输出。流会聚合 为一个 MCP 结果；部分 token 不会作为 MCP 通知转发。

搜索与抓取计费说明

DeepSeek 于 2026 年 10 月 17 日推出了独立的搜索和抓取 API。 每 1,000 次成功请求收费 $0.75，按请求而非 token 或结果数量计费。只有返回 HTTP 200 且 包含非空搜索结果或抓取页面内容的请求才会计费。这些费用与模型 token 费用分开计算。

DeepSeek 表示，通过服务端工具在 DeepSeek Harness、Claude Code 和 Codex 中发起的搜索和抓取调用， 目前对 DeepSeek API 用户暂时免费；按请求计费将于 2026 年 10 月 31 日 16:00 UTC （北京时间 11 月 1 日 00:00）开始。这项已公布的豁免仅列出这些客户端； 不要假设其他集成也适用。启用 Agent 搜索功能前，请查看 DeepSeek 当前的定价。

此 MCP 服务不提供独立的搜索或抓取工具。其 create_response 工具已支持 Pro 使用 web_search，由 DeepSeek 在其服务器上运行；Flash 会忽略它。 新增的原始 JSON 端点为 POST /v1/tools/search 和 POST /v1/tools/fetch。服务的 MCP_TOOL_RATE_LIMIT 限制 MCP 调用次数，不限制 DeepSeek 费用。

安装

需要 Node.js 20 或更高版本。

通过 stdio 直接运行：

DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" npx -y deepseek-mcp-server@1

Codex CLI：

codex mcp add deepseek --env DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" -- npx -y deepseek-mcp-server@1

Claude Code：

claude mcp add deepseek --env DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" -- npx -y deepseek-mcp-server@1

MCP 客户端配置示例：

{
  "mcpServers": {
    "deepseek": {
      "command": "npx",
      "args": ["-y", "deepseek-mcp-server@1"],
      "env": {
        "DEEPSEEK_API_KEY": "REPLACE_WITH_DEEPSEEK_KEY"
      }
    }
  }
}

视觉输入

chat_completion 接受图像 URL：

{
  "message": [
    { "type": "text", "text": "Describe this image." },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.png",
        "detail": "high"
      }
    }
  ]
}

它还接受受支持的 base64 数据 URL，无需先上传：

{
  "message": [
    { "type": "text", "text": "What is shown here?" },
    {
      "type": "file",
      "file_data": "data:image/png;base64,iVBORw0KGgo...",
      "filename": "image.png"
    }
  ]
}

如需重复使用，请调用 upload_file，然后传入其返回的 ID：

{
  "filename": "diagram.png",
  "file_data": "iVBORw0KGgo...",
  "expires_after_seconds": 86400
}

{
  "message": [
    { "type": "text", "text": "Explain this diagram." },
    { "type": "file", "file_id": "file-api-..." }
  ]
}

同一上传文件也可用于 create_response：

{
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Read the image." },
        { "type": "input_image", "file_id": "file-api-..." }
      ]
    }
  ]
}

支持的图像格式包括 JPEG、PNG、GIF 和 WebP。细节级别可为 low、 high、original 或 auto。

图像限制

内联图像每个最大为 32 MiB，上传文件最大为 64 MiB，JSON 请求正文最大为 48 MiB，单个请求最多包含 600 张图像。本地验证会检查已知的内联图像大小、图像数量以及序列化后的 UTF-8 正文大小。DeepSeek 会检查远程／下载图像和上传文件的尺寸及总大小：不含文件引用时总计 64 MiB，包含文件引用时总计 200 MiB。图像每边尺寸不得超过 8192 像素；图像数量达到 15 张时，限制降至 4096 像素。外部下载必须在 60 秒内完成。

仅为了预先检查这些服务商侧限制，服务不会获取图像 URL 或读取文件元数据。对于大型图像或重复使用的图像，请使用 Files API。

上传安全边界

upload_file 接受原始 base64 数据或受支持的图像 data URL。它有意不接受本地文件路径，也不会在服务端获取任意 URL。解码后的上传文件最大为 64 MiB，上传前会检查字节签名。上传的数据由 DeepSeek 存储在你的账户下；如果不希望数据持续保留，请设置过期时间或使用 delete_file。过期时间必须介于 3,600 到 2,592,000 秒之间。DeepSeek 存储空间限制为每位用户 25 GiB 和 10,000 个文件。上传期限为十分钟；如有需要，可为大型上传调高 DEEPSEEK_REQUEST_TIMEOUT_MS。

Streamable HTTP

运行本地 HTTP 端点：

DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" \
MCP_TRANSPORT=streamable-http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3001 \
npx -y deepseek-mcp-server@1

端点默认为 http://127.0.0.1:3001/mcp。

对于浏览器客户端，请设置精确的逗号分隔来源允许列表：

MCP_HTTP_ALLOWED_ORIGINS=https://app.example.com,http://localhost:3000

除非来源已列入允许列表，否则带有 Origin 标头的请求会被拒绝，并返回 403。未发送 Origin 的原生客户端不受影响。

HTTP 身份验证与准入限制

默认情况下，本地 HTTP 绑定到环回地址。若要使用共享 Bearer 令牌保护它，请设置 MCP_HTTP_AUTH_TOKEN；调用方随后需发送 Authorization: Bearer <token>。这是共享令牌访问控制，并非 OAuth 授权服务器。

现在，非环回地址绑定必须设置 MCP_HTTP_AUTH_TOKEN 或 MCP_HTTP_TRUST_AUTH_GATEWAY=true。仅当反向代理会对每个 MCP 请求进行身份验证并阻止直接访问后端时，才使用网关模式。浏览器来源允许列表独立于身份验证。升级自 1.0.1 的托管部署必须显式配置其中一种身份验证方式。

MCP_TOOL_RATE_LIMIT 默认限制为每个 60 秒时间窗口调用 120 次，并由使用同一服务商客户端的所有工具和无状态 HTTP 请求实例共享。速率限制响应属于 MCP 工具错误，包含 error_type=tool_rate_limit 和 retryable=true；被拒绝的调用不会到达 DeepSeek，也不会更改对话。

MCP 取消操作会传递到服务商请求。已取消的回复不会保存到对话历史记录。读取不存在的对话资源会返回协议规定的 -32602 错误。服务不会公布资源列表变更通知。

托管端点

另有一个独立部署的端点，地址为 https://deepseek-mcp.ragweld.com/mcp，使用 Authorization: Bearer <token>。托管部署有自己的发布周期，可能落后于 npm/GitHub 版本；依赖新添加的工具前，请先检查 tools/list。

环境

必需：

DEEPSEEK_API_KEY=your-api-key

可选：

DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_REQUEST_TIMEOUT_MS=120000
DEEPSEEK_DEFAULT_MODEL=deepseek-flash
MCP_TRANSPORT=stdio
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3001
MCP_HTTP_PATH=/mcp
MCP_HTTP_ALLOWED_ORIGINS=https://app.example.com,http://localhost:3000
MCP_HTTP_AUTH_TOKEN=
MCP_HTTP_TRUST_AUTH_GATEWAY=false
MCP_TOOL_RATE_LIMIT=120
CONVERSATION_MAX_MESSAGES=200

CONVERSATION_MAX_MESSAGES 限制进程本地存储中每个对话保留的消息数。重启进程会清除此存储。

MCP 兼容性

• 基于 @modelcontextprotocol/server 和 @modelcontextprotocol/client 2.3.1，以及 @modelcontextprotocol/node 2.1.1 构建。
• 现代 MCP 2026-07-28 是无状态的：发现使用 server/discover， 请求会在 _meta 中携带协议版本和客户端能力，已完成的结果会携带 resultType 和必需的缓存字段。SDK 会验证相应的 HTTP 标头。仍可为较旧的客户端 使用 2025 年版的无状态处理方式。
• Stdio 会根据初始交换选择协议时代，并为该连接固定一个服务实例。
• 静态发现／列表结果会携带一小时的公开缓存提示；动态资源列表、运行时数据、实时账户数据和对话仍为私有，且有效期较短或不缓存。
• 显式的 conversation_id 记忆属于应用状态，与传输会话状态相互独立。

从 0.6.0 迁移

• 默认模型从 deepseek-v4-flash 更改为 deepseek-flash。
• MCP SDK 从单体 v1 软件包迁移到拆分后的 v2 软件包。
• 已移除 MCP_HTTP_STATEFUL_SESSION。HTTP 协议处理现在按请求进行／采用无状态方式；请使用 conversation_id 保留聊天上下文。
• 新增了 4 个 Files API 工具和视觉输入。
• 现有工具名称和 include_raw_response 行为保持兼容。

发布版本 1.4.0

此版本更新了 MCP 依赖项，修正了 Pro 可用性和 Responses 功能，新增了 apply_patch 自定义工具结果和 FIM 使用选项，并修复了 beta 路由、端到端请求截止时间、拆分 CRLF SSE 边界、流错误处理以及非 JSON 提供方错误。保留现有工具名称和选择启用的原始响应。完整的 API／MCP 审计还新增了视觉请求限制、完整的 Responses 历史记录、取消传播、准确的功能声明、缺失资源错误、工具准入限制、反射凭据脱敏以及显式远程 HTTP 身份验证。 DEEPSEEK_DEFAULT_MODEL 现在会被全部 3 个生成工具采用。

此前的 1.1.0–1.3.0 版本标识曾发布后又被移除；npm 无法重复使用这些版本。下一个可用的次版本为 1.4.0。

开发与验证

npm ci
npm run build
npm test
npm pack --dry-run

需要凭据的冒烟测试：

DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" npm run test:live
DEEPSEEK_MCP_AUTH_TOKEN="REPLACE_WITH_TOKEN" npm run test:remote

在线冒烟测试涵盖模型列表、余额、文本聊天、思考流式传输、Responses、严格的 beta 函数调用、apply_patch 自定义工具调用、FIM、视觉输入，以及包含清理步骤的 Files 上传／检索／列表／删除生命周期。

Registry 标识

• MCP Registry：io.github.DMontgomery40/deepseek
• npm：[email protected]
• OCI：docker.io/dmontgomery40/deepseek-mcp-server:0.5.0 是最后发布的镜像，不包含当前 npm 功能集。

文档审计

本次发布审计涵盖所有受支持的 DeepSeek 端点引用及其当前指南，以及全部 31 个页面和 MCP 2026-07-28 的权威架构。审计发现、覆盖范围、来源冲突、可选功能和验证限制记录在 API 审计 和 MCP 审计中。已阅读 Anthropic 格式的提供方 API 以供参考；此服务提供与 OpenAI 兼容的 Chat、Responses、FIM、Files、模型和余额路由。

官方参考资料

• DeepSeek 更新日志
• DeepSeek 10 月 17 日公告
• DeepSeek 搜索与抓取指南及计费说明
• DeepSeek Responses 兼容性指南
• DeepSeek V4.1 Flash 公告
• DeepSeek 定价与模型限制
• DeepSeek 视觉输入指南
• DeepSeek Files API 指南
• DeepSeek Chat Completions
• DeepSeek Responses API
• MCP 2026-07-28 规范
• MCP TypeScript SDK v2
• MCP SDK v2 迁移指南

许可证

MIT