Skip to content
Back to search

deepseek-mcp-server

Model Context Protocol server for DeepSeek's advanced language models

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dmontgomery40--deepseek-mcp-server/badge.svg)](/listings/dmontgomery40--deepseek-mcp-server)

HTML

<a href="/listings/dmontgomery40--deepseek-mcp-server"><img src="/api/listings/dmontgomery40--deepseek-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Node.js 20 or newer is required.

Run directly over 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

Example MCP client configuration:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 434 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DeepSeek MCP Server
  2. <p align="center">
  3. <a href="https://github.com/deepseek-ai/awesome-deepseek-integration"><img alt="DeepSeek Official List" src="https://img.shields.io/badge/DeepSeek%20Official%20List-Linked-0A66FF?logo=github&logoColor=white" /></a>
  4. <a href="https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DMontgomery40/deepseek"><img alt="Official MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-Official%20Active-0A66FF" /></a>
  5. <a href="https://www.npmjs.com/package/deepseek-mcp-server"><img alt="npm version" src="https://img.shields.io/npm/v/deepseek-mcp-server?logo=npm" /></a>
  6. <a href="https://www.npmjs.com/package/deepseek-mcp-server"><img alt="npm downloads" src="https://img.shields.io/npm/dm/deepseek-mcp-server?logo=npm" /></a>
  7. <a href="https://github.com/DMontgomery40/deepseek-mcp-server/blob/main/server.json"><img alt="Last published OCI package" src="https://img.shields.io/badge/OCI%20(last%20published)-0.5.0-2496ED?logo=docker&logoColor=white" /></a>
  8. <a href="https://github.com/DMontgomery40/deepseek-mcp-server"><img alt="GitHub stars" src="https://img.shields.io/github/stars/DMontgomery40/deepseek-mcp-server?logo=github" /></a>
  9. <a href="https://glama.ai/mcp/servers/asht4rqltn"><img alt="Glama MCP Listing" src="https://img.shields.io/badge/Glama-MCP%20Listing-7B61FF" /></a>
  10. </p>
  11. An MCP server for DeepSeek V4.1 Flash and V4 Pro APIs: text and visual chat, the
  12. Responses API, FIM completion, Files API lifecycle operations, model discovery,
  13. balance checks, and bounded in-memory conversations.
  14. Version 1.4.1 uses the stable MCP TypeScript SDK v2 and serves both the
  15. 2026-07-28 protocol and stateless legacy clients.
  16. ## What's current
  17. Checked against the official API docs on October 19, 2026:
  18. - The canonical fast model is `deepseek-flash`, now served by
  19. DeepSeek-V4.1-Flash-1017. The October 17 model update did not change its API
  20. calling method or model-token pricing.
  21. - `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` are temporary aliases
  22. for `deepseek-flash`.
  23. - `deepseek-v4-pro` continues serving V4 Pro 0813. DeepSeek reversed its
  24. announced September rerouting plan; Pro remains available with unchanged billing.
  25. - V4.1 Flash accepts visual input through Chat Completions and Responses.
  26. V4 Pro accepts text input. Use `list_models` to check your account's live availability.
  27. - The Files API supports upload, list, retrieve, and delete for reusable image
  28. inputs.
  29. - DeepSeek documents a 1M-token context window and up to 384K output tokens for
  30. `deepseek-flash`.
  31. “Multimodal” here means image understanding. This server does not generate
  32. images, video, or audio.
  33. ## Tools
  34. The server exposes eleven tools:
  35. - `chat_completion`: text or visual Chat Completions, thinking controls,
  36. function tools, JSON output, streaming aggregation, and optional
  37. `conversation_id` memory.
  38. - `create_response`: stateless Responses API calls with text/images, reasoning
  39. controls, function tools, the `apply_patch` custom tool, structured output, and semantic
  40. streaming aggregation.
  41. - `completion`: FIM completion through `/beta/completions`.
  42. - `list_models`: live model discovery, including display names, context/output
  43. limits, input/output modalities, effort levels, and API capabilities.
  44. - `get_user_balance`: account availability and balances.
  45. - `upload_file`: upload base64 JPEG, PNG, GIF, or WebP data and receive a
  46. reusable DeepSeek `file_id`.
  47. - `list_files`: list uploaded files with cursor, order, and purpose filters.
  48. - `retrieve_file`: retrieve metadata for one `file_id`.
  49. - `delete_file`: delete one uploaded file.
  50. - `reset_conversation`: clear one local in-memory conversation.
  51. - `list_conversations`: list local in-memory conversation IDs.
  52. Every tool declares an MCP output schema and behavior annotations. Full
  53. provider payloads remain opt-in through `include_raw_response=true`.
  54. ## API behavior
  55. - Thinking is enabled by default. Canonical reasoning efforts are `none`,
  56. `low`, `high`, and `max`. Compatibility aliases are accepted: `minimal` maps
  57. to `low`; `medium` and `xhigh` map to `high`; the thinking guide also accepts
  58. `ultra` as an alias for `max`.
  59. - Chat `stream_options` requires `stream=true`. Chat forced tool choices
  60. (`required` or a named function) require thinking to be disabled.
  61. - Chat prefix completion (`prefix=true`) and strict function tools
  62. (`strict=true`) automatically use `/beta/chat/completions`. Configured `/v1`
  63. and `/beta` bases are normalized for beta requests.
  64. - Frequency and presence penalties remain accepted for compatibility, but
  65. DeepSeek ignores them.
  66. - Responses calls are stateless: send full input history. `web_search` runs
  67. server-side with `deepseek-v4-pro`; DeepSeek ignores it with `deepseek-flash`.
  68. Other built-in tool types such as `file_search`, `code_interpreter`, and `mcp`
  69. are ignored. The supported custom tool is
  70. `{ "type": "custom", "name": "apply_patch" }`. Returned calls appear in
  71. `custom_tool_calls`; the client is responsible for executing them and
  72. sending `custom_tool_call_output` history. `output_items` preserves complete
  73. returned reasoning, message, and tool-call items for replay without enabling
  74. the full raw provider response.
  75. - FIM is beta and non-thinking. It supports streaming usage options;
  76. `echo=true` cannot accompany `suffix` or `logprobs`. Its guide documents a
  77. 4K output limit, so do not assume the Chat output ceiling applies.
  78. - `DEEPSEEK_REQUEST_TIMEOUT_MS` applies to the complete request, including
  79. reading the response body and streaming output. Streams are aggregated
  80. into one MCP result; partial tokens are not forwarded as MCP notifications.
  81. ## Search and Fetch billing notice
  82. DeepSeek opened separate [Search and Fetch APIs](https://api-docs.deepseek.com/guides/search/)
  83. on October 17, 2026. Each costs **$0.75 per 1,000 successful requests**, billed
  84. by request rather than tokens or result count. A request is billable only if it
  85. returns HTTP 200 with a non-empty Search result or Fetch page content. These
  86. charges are separate from model-token charges.
  87. DeepSeek says Search and Fetch calls made through server-side tools in
  88. **DeepSeek Harness, Claude Code, and Codex** are temporarily free for DeepSeek
  89. API users; per-request billing starts **October 31, 2026 at 16:00 UTC**
  90. (November 1 at 00:00 Beijing time). This announced waiver names those clients;
  91. do not assume it covers other integrations. Check DeepSeek's current pricing
  92. before enabling search in an agent.
  93. This MCP server does not expose standalone Search or Fetch tools. Its
  94. `create_response` tool already accepts `web_search` for Pro, which DeepSeek
  95. runs on its server; Flash ignores it. The new raw JSON endpoints are
  96. `POST /v1/tools/search` and `POST /v1/tools/fetch`. The server's
  97. `MCP_TOOL_RATE_LIMIT` limits MCP invocations, not DeepSeek spending.
  98. ## Install
  99. Node.js 20 or newer is required.
  100. Run directly over stdio:
  101. ```bash
  102. DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" npx -y deepseek-mcp-server@1
  103. ```
  104. Codex CLI:
  105. ```bash
  106. codex mcp add deepseek --env DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" -- npx -y deepseek-mcp-server@1
  107. ```
  108. Claude Code:
  109. ```bash
  110. claude mcp add deepseek --env DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" -- npx -y deepseek-mcp-server@1
  111. ```
  112. Example MCP client configuration:
  113. ```json
  114. {
  115. "mcpServers": {
  116. "deepseek": {
  117. "command": "npx",
  118. "args": ["-y", "deepseek-mcp-server@1"],
  119. "env": {
  120. "DEEPSEEK_API_KEY": "REPLACE_WITH_DEEPSEEK_KEY"
  121. }
  122. }
  123. }
  124. }
  125. ```
  126. ## Visual input
  127. `chat_completion` accepts image URLs:
  128. ```json
  129. {
  130. "message": [
  131. { "type": "text", "text": "Describe this image." },
  132. {
  133. "type": "image_url",
  134. "image_url": {
  135. "url": "https://example.com/photo.png",
  136. "detail": "high"
  137. }
  138. }
  139. ]
  140. }
  141. ```
  142. It also accepts a supported base64 data URL without first uploading it:
  143. ```json
  144. {
  145. "message": [
  146. { "type": "text", "text": "What is shown here?" },
  147. {
  148. "type": "file",
  149. "file_data": "data:image/png;base64,iVBORw0KGgo...",
  150. "filename": "image.png"
  151. }
  152. ]
  153. }
  154. ```
  155. For reuse, call `upload_file`, then pass its returned ID:
  156. ```json
  157. {
  158. "filename": "diagram.png",
  159. "file_data": "iVBORw0KGgo...",
  160. "expires_after_seconds": 86400
  161. }
  162. ```
  163. ```json
  164. {
  165. "message": [
  166. { "type": "text", "text": "Explain this diagram." },
  167. { "type": "file", "file_id": "file-api-..." }
  168. ]
  169. }
  170. ```
  171. The same uploaded file can be used with `create_response`:
  172. ```json
  173. {
  174. "input": [
  175. {
  176. "role": "user",
  177. "content": [
  178. { "type": "input_text", "text": "Read the image." },
  179. { "type": "input_image", "file_id": "file-api-..." }
  180. ]
  181. }
  182. ]
  183. }
  184. ```
  185. Supported image formats are JPEG, PNG, GIF, and WebP. Detail may be `low`,
  186. `high`, `original`, or `auto`.
  187. ### Image limits
  188. Inline images are limited to 32 MiB each, uploaded Files to 64 MiB, JSON
  189. request bodies to 48 MiB, and requests to 600 images. Local validation checks
  190. known inline sizes, image counts, and serialized UTF-8 body size. DeepSeek
  191. checks remote/downloaded and uploaded-file dimensions and aggregate sizes:
  192. 64 MiB total without file references, or 200 MiB including them. Dimensions
  193. are limited to 8192 pixels per side, dropping to 4096 when there are at least
  194. 15 images. External downloads must complete within 60 seconds.
  195. The server does not fetch image URLs or read file metadata just to preflight
  196. these provider-side limits. Use the Files API for large or reused images.
  197. ### Upload safety boundary
  198. `upload_file` accepts raw base64 or a supported image data URL. It deliberately
  199. does not accept local file paths and does not fetch arbitrary URLs on the
  200. server. Decoded uploads are limited to 64 MiB, and the bytes are
  201. signature-checked before upload. Uploaded data is stored by DeepSeek under your
  202. account; use an expiry or `delete_file` when it should not persist. Expiry must
  203. be between 3,600 and 2,592,000 seconds. DeepSeek storage is limited to 25 GiB
  204. and 10,000 files per user. Its upload deadline is ten minutes; increase
  205. `DEEPSEEK_REQUEST_TIMEOUT_MS` for large uploads when needed.
  206. ## Streamable HTTP
  207. Run a local HTTP endpoint:
  208. ```bash
  209. DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" \
  210. MCP_TRANSPORT=streamable-http \
  211. MCP_HTTP_HOST=127.0.0.1 \
  212. MCP_HTTP_PORT=3001 \
  213. npx -y deepseek-mcp-server@1
  214. ```
  215. The endpoint defaults to `http://127.0.0.1:3001/mcp`.
  216. For browser clients, set an exact comma-separated origin allowlist:
  217. ```bash
  218. MCP_HTTP_ALLOWED_ORIGINS=https://app.example.com,http://localhost:3000
  219. ```
  220. Requests that include an `Origin` header are rejected with `403` unless the
  221. origin is allowlisted. Native clients that omit `Origin` are unaffected.
  222. ### HTTP authentication and admission limits
  223. Local HTTP binds to loopback by default. To protect it with a shared bearer
  224. token, set `MCP_HTTP_AUTH_TOKEN`; callers then send `Authorization: Bearer <token>`.
  225. This is shared-token access control, not an OAuth authorization server.
  226. Non-loopback binds now require either `MCP_HTTP_AUTH_TOKEN` or
  227. `MCP_HTTP_TRUST_AUTH_GATEWAY=true`. Use gateway mode only when a reverse proxy
  228. authenticates every MCP request and prevents direct access to the backend.
  229. A browser origin allowlist is independent of authentication. Hosted installations
  230. upgrading from 1.0.1 must explicitly configure one of these authentication paths.
  231. `MCP_TOOL_RATE_LIMIT` defaults to 120 invocations per 60-second window, shared
  232. across all tools and stateless HTTP request instances using the same provider
  233. client. Rate-limit responses are MCP tool errors with `error_type=tool_rate_limit`
  234. and `retryable=true`; denied calls do not reach DeepSeek or alter conversations.
  235. MCP cancellation reaches the provider request. Cancelled replies are not saved
  236. to conversation history. Reading a missing conversation resource returns the
  237. protocol's `-32602` error. Resource list-change notifications are not advertised.
  238. ### Hosted endpoint
  239. A separately deployed endpoint is available at
  240. `https://deepseek-mcp.ragweld.com/mcp` using
  241. `Authorization: Bearer <token>`. The hosted deployment has its own release
  242. cycle and may lag the npm/GitHub release; inspect `tools/list` before relying
  243. on a newly added tool.
  244. ## Environment
  245. Required:
  246. ```bash
  247. DEEPSEEK_API_KEY=your-api-key
  248. ```
  249. Optional:
  250. ```bash
  251. DEEPSEEK_BASE_URL=https://api.deepseek.com
  252. DEEPSEEK_REQUEST_TIMEOUT_MS=120000
  253. DEEPSEEK_DEFAULT_MODEL=deepseek-flash
  254. MCP_TRANSPORT=stdio
  255. MCP_HTTP_HOST=127.0.0.1
  256. MCP_HTTP_PORT=3001
  257. MCP_HTTP_PATH=/mcp
  258. MCP_HTTP_ALLOWED_ORIGINS=https://app.example.com,http://localhost:3000
  259. MCP_HTTP_AUTH_TOKEN=
  260. MCP_HTTP_TRUST_AUTH_GATEWAY=false
  261. MCP_TOOL_RATE_LIMIT=120
  262. CONVERSATION_MAX_MESSAGES=200
  263. ```
  264. `CONVERSATION_MAX_MESSAGES` bounds the messages retained per conversation in
  265. the process-local store. Restarting the process clears this store.
  266. ## MCP compatibility
  267. - Built on `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
  268. 2.3.1, with `@modelcontextprotocol/node` 2.1.1.
  269. - Modern MCP 2026-07-28 is stateless: discovery uses `server/discover`,
  270. requests carry protocol version and client capabilities in `_meta`, and
  271. completed results carry `resultType` and required caching fields. The SDK
  272. validates the corresponding HTTP headers. Stateless 2025-era handling
  273. remains available for older clients.
  274. - Stdio chooses the protocol era from the opening exchange and pins one server
  275. instance for that connection.
  276. - Static discovery/list results carry one-hour public cache hints; dynamic
  277. resource lists, runtime data, live account data, and conversations remain
  278. private and short-lived or uncached.
  279. - Explicit `conversation_id` memory is application state and works independently
  280. of transport session state.
  281. ### Migrating from 0.6.0
  282. - The default model changed from `deepseek-v4-flash` to `deepseek-flash`.
  283. - The MCP SDK moved from the monolithic v1 package to the split v2 packages.
  284. - `MCP_HTTP_STATEFUL_SESSION` was removed. HTTP protocol handling is now
  285. per-request/stateless; use `conversation_id` for retained chat context.
  286. - Four Files API tools and visual inputs were added.
  287. - Existing tool names and `include_raw_response` behavior remain compatible.
  288. ## Release 1.4.1
  289. Preserves leading system instructions and removes orphaned tool results when
  290. conversation history reaches its configured cap. Refreshes the MCP Node adapter
  291. and locks `@hono/node-server` to 2.1.5 to clear GHSA-rmxm-3fg6-px4f. This server
  292. does not use the affected `serveStatic` helper. HTTP startup supplies Node's Web
  293. Crypto only when the global is missing. Node >=20 support is unchanged.
  294. ## Release 1.4.0
  295. This release refreshes MCP dependencies, corrects Pro availability and Responses
  296. capabilities, adds `apply_patch` custom-tool results and FIM usage options, and
  297. fixes beta routing, end-to-end request deadlines, split CRLF SSE boundaries,
  298. stream error handling, and non-JSON provider errors. Existing tool names and
  299. opt-in raw responses are preserved. The complete API/MCP audit also adds
  300. vision request limits, complete Responses history, cancellation propagation,
  301. truthful capabilities, missing-resource errors, tool admission limits,
  302. reflected-credential redaction, and explicit remote HTTP authentication.
  303. `DEEPSEEK_DEFAULT_MODEL` is now honored by all three generation tools.
  304. Earlier 1.1.0–1.3.0 version identifiers were historically published and removed;
  305. npm cannot reuse them. The next available minor release is 1.4.0.
  306. ## Development and verification
  307. ```bash
  308. npm ci
  309. npm run build
  310. npm test
  311. npm pack --dry-run
  312. ```
  313. Credentialed smoke tests:
  314. ```bash
  315. DEEPSEEK_API_KEY="REPLACE_WITH_DEEPSEEK_KEY" npm run test:live
  316. DEEPSEEK_MCP_AUTH_TOKEN="REPLACE_WITH_TOKEN" npm run test:remote
  317. ```
  318. The live smoke covers model listing, balance, text chat, thinking streaming,
  319. Responses, strict beta function calling, `apply_patch` custom-tool calls, FIM,
  320. visual input, and a Files upload/retrieve/list/delete lifecycle with cleanup.
  321. ## Registry identity
  322. - MCP Registry: `io.github.DMontgomery40/deepseek`
  323. - npm: `deepseek-mcp-server@1.4.1`
  324. - OCI: `docker.io/dmontgomery40/deepseek-mcp-server:0.5.0` is the last
  325. published image and does not contain the current npm feature set.
  326. ## Documentation audit
  327. The release audit covers every supported DeepSeek endpoint reference and its
  328. current guides, plus all 31 pages and the authoritative schema of MCP
  329. 2026-07-28. Findings, coverage, source conflicts, optional capabilities, and
  330. verification limits are recorded in [the API audit](docs/research/2026-10-13-api-mcp-update.md)
  331. and [the MCP audit](docs/research/2026-10-13-mcp-spec-audit.md). Anthropic-format
  332. provider APIs were read for context; this server exposes the OpenAI-compatible
  333. Chat, Responses, FIM, Files, model, and balance routes.
  334. ## Official references
  335. - [DeepSeek changelog](https://api-docs.deepseek.com/updates/)
  336. - [DeepSeek October 17 announcement](https://api-docs.deepseek.com/news/news261017/)
  337. - [DeepSeek Search and Fetch guide and billing](https://api-docs.deepseek.com/guides/search/)
  338. - [DeepSeek Responses compatibility guide](https://api-docs.deepseek.com/guides/responses_api/)
  339. - [DeepSeek V4.1 Flash announcement](https://api-docs.deepseek.com/news/news260910/)
  340. - [DeepSeek pricing and model limits](https://api-docs.deepseek.com/quick_start/pricing/)
  341. - [DeepSeek visual input guide](https://api-docs.deepseek.com/guides/vision/)
  342. - [DeepSeek Files API guide](https://api-docs.deepseek.com/guides/files_api/)
  343. - [DeepSeek Chat Completions](https://api-docs.deepseek.com/api/create-chat-completion/)
  344. - [DeepSeek Responses API](https://api-docs.deepseek.com/api/create-response/)
  345. - [MCP 2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28)
  346. - [MCP TypeScript SDK v2](https://github.com/modelcontextprotocol/typescript-sdk)
  347. - [MCP SDK v2 migration guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/upgrade-to-v2.md)
  348. ## License
  349. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.