DeepSeek MCP Server

DeepSeek MCP Server

An MCP server for DeepSeek V4.1 Flash and V4 Pro APIs: text and visual chat, the Responses API, FIM completion, Files API lifecycle operations, model discovery, balance checks, and bounded in-memory conversations.

Version 1.4.0 uses the stable MCP TypeScript SDK v2 and serves both the 2026-07-28 protocol and stateless legacy clients.

What's current

Checked against the official API docs on October 19, 2026:

• The canonical fast model is deepseek-flash, now served by DeepSeek-V4.1-Flash-1017. The October 17 model update did not change its API calling method or model-token pricing.
• deepseek-v4-flash and deepseek-v4-flash-vision-exp are temporary aliases for deepseek-flash.
• deepseek-v4-pro continues serving V4 Pro 0813. DeepSeek reversed its announced September rerouting plan; Pro remains available with unchanged billing.
• V4.1 Flash accepts visual input through Chat Completions and Responses. V4 Pro accepts text input. Use list_models to check your account's live availability.
• The Files API supports upload, list, retrieve, and delete for reusable image inputs.
• DeepSeek documents a 1M-token context window and up to 384K output tokens for deepseek-flash.

“Multimodal” here means image understanding. This server does not generate images, video, or audio.

Tools

The server exposes eleven tools:

• chat_completion: text or visual Chat Completions, thinking controls, function tools, JSON output, streaming aggregation, and optional conversation_id memory.
• create_response: stateless Responses API calls with text/images, reasoning controls, function tools, the apply_patch custom tool, structured output, and semantic streaming aggregation.
• completion: FIM completion through /beta/completions.
• list_models: live model discovery, including display names, context/output limits, input/output modalities, effort levels, and API capabilities.
• get_user_balance: account availability and balances.
• upload_file: upload base64 JPEG, PNG, GIF, or WebP data and receive a reusable DeepSeek file_id.
• list_files: list uploaded files with cursor, order, and purpose filters.
• retrieve_file: retrieve metadata for one file_id.
• delete_file: delete one uploaded file.
• reset_conversation: clear one local in-memory conversation.
• list_conversations: list local in-memory conversation IDs.

Every tool declares an MCP output schema and behavior annotations. Full provider payloads remain opt-in through include_raw_response=true.

API behavior

• Thinking is enabled by default. Canonical reasoning efforts are none, low, high, and max. Compatibility aliases are accepted: minimal maps to low; medium and xhigh map to high; the thinking guide also accepts ultra as an alias for max.
• Chat stream_options requires stream=true. Chat forced tool choices (required or a named function) require thinking to be disabled.
• Chat prefix completion (prefix=true) and strict function tools (strict=true) automatically use /beta/chat/completions. Configured /v1 and /beta bases are normalized for beta requests.
• Frequency and presence penalties remain accepted for compatibility, but DeepSeek ignores them.
• Responses calls are stateless: send full input history. web_search runs server-side with deepseek-v4-pro; DeepSeek ignores it with deepseek-flash. Other built-in tool types such as file_search, code_interpreter, and mcp are ignored. The supported custom tool is { "type": "custom", "name": "apply_patch" }. Returned calls appear in custom_tool_calls; the client is responsible for executing them and sending custom_tool_call_output history. output_items preserves complete returned reasoning, message, and tool-call items for replay without enabling the full raw provider response.
• FIM is beta and non-thinking. It supports streaming usage options; echo=true cannot accompany suffix or logprobs. Its guide documents a 4K output limit, so do not assume the Chat output ceiling applies.
• DEEPSEEK_REQUEST_TIMEOUT_MS applies to the complete request, including reading the response body and streaming output. Streams are aggregated into one MCP result; partial tokens are not forwarded as MCP notifications.

Search and Fetch billing notice

DeepSeek opened separate Search and Fetch APIs on October 17, 2026. Each costs $0.75 per 1,000 successful requests, billed by request rather than tokens or result count. A request is billable only if it returns HTTP 200 with a non-empty Search result or Fetch page content. These charges are separate from model-token charges.

DeepSeek says Search and Fetch calls made through server-side tools in DeepSeek Harness, Claude Code, and Codex are temporarily free for DeepSeek API users; per-request billing starts October 31, 2026 at 16:00 UTC (November 1 at 00:00 Beijing time). This announced waiver names those clients; do not assume it covers other integrations. Check DeepSeek's current pricing before enabling search in an agent.

This MCP server does not expose standalone Search or Fetch tools. Its create_response tool already accepts web_search for Pro, which DeepSeek runs on its server; Flash ignores it. The new raw JSON endpoints are POST /v1/tools/search and POST /v1/tools/fetch. The server's MCP_TOOL_RATE_LIMIT limits MCP invocations, not DeepSeek spending.

Install

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"
      }
    }
  }
}

Visual input

chat_completion accepts image URLs:

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

It also accepts a supported base64 data URL without first uploading it:

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

For reuse, call upload_file, then pass its returned ID:

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

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

The same uploaded file can be used with create_response:

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

Supported image formats are JPEG, PNG, GIF, and WebP. Detail may be low, high, original, or auto.

Image limits

Inline images are limited to 32 MiB each, uploaded Files to 64 MiB, JSON request bodies to 48 MiB, and requests to 600 images. Local validation checks known inline sizes, image counts, and serialized UTF-8 body size. DeepSeek checks remote/downloaded and uploaded-file dimensions and aggregate sizes: 64 MiB total without file references, or 200 MiB including them. Dimensions are limited to 8192 pixels per side, dropping to 4096 when there are at least 15 images. External downloads must complete within 60 seconds.

The server does not fetch image URLs or read file metadata just to preflight these provider-side limits. Use the Files API for large or reused images.

Upload safety boundary

upload_file accepts raw base64 or a supported image data URL. It deliberately does not accept local file paths and does not fetch arbitrary URLs on the server. Decoded uploads are limited to 64 MiB, and the bytes are signature-checked before upload. Uploaded data is stored by DeepSeek under your account; use an expiry or delete_file when it should not persist. Expiry must be between 3,600 and 2,592,000 seconds. DeepSeek storage is limited to 25 GiB and 10,000 files per user. Its upload deadline is ten minutes; increase DEEPSEEK_REQUEST_TIMEOUT_MS for large uploads when needed.

Streamable HTTP

Run a local HTTP endpoint:

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

The endpoint defaults to http://127.0.0.1:3001/mcp.

For browser clients, set an exact comma-separated origin allowlist:

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

Requests that include an Origin header are rejected with 403 unless the origin is allowlisted. Native clients that omit Origin are unaffected.

HTTP authentication and admission limits

Local HTTP binds to loopback by default. To protect it with a shared bearer token, set MCP_HTTP_AUTH_TOKEN; callers then send Authorization: Bearer <token>. This is shared-token access control, not an OAuth authorization server.

Non-loopback binds now require either MCP_HTTP_AUTH_TOKEN or MCP_HTTP_TRUST_AUTH_GATEWAY=true. Use gateway mode only when a reverse proxy authenticates every MCP request and prevents direct access to the backend. A browser origin allowlist is independent of authentication. Hosted installations upgrading from 1.0.1 must explicitly configure one of these authentication paths.

MCP_TOOL_RATE_LIMIT defaults to 120 invocations per 60-second window, shared across all tools and stateless HTTP request instances using the same provider client. Rate-limit responses are MCP tool errors with error_type=tool_rate_limit and retryable=true; denied calls do not reach DeepSeek or alter conversations.

MCP cancellation reaches the provider request. Cancelled replies are not saved to conversation history. Reading a missing conversation resource returns the protocol's -32602 error. Resource list-change notifications are not advertised.

Hosted endpoint

A separately deployed endpoint is available at https://deepseek-mcp.ragweld.com/mcp using Authorization: Bearer <token>. The hosted deployment has its own release cycle and may lag the npm/GitHub release; inspect tools/list before relying on a newly added tool.

Environment

Required:

DEEPSEEK_API_KEY=your-api-key

Optional:

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 bounds the messages retained per conversation in the process-local store. Restarting the process clears this store.

MCP compatibility

• Built on @modelcontextprotocol/server and @modelcontextprotocol/client 2.3.1, with @modelcontextprotocol/node 2.1.1.
• Modern MCP 2026-07-28 is stateless: discovery uses server/discover, requests carry protocol version and client capabilities in _meta, and completed results carry resultType and required caching fields. The SDK validates the corresponding HTTP headers. Stateless 2025-era handling remains available for older clients.
• Stdio chooses the protocol era from the opening exchange and pins one server instance for that connection.
• Static discovery/list results carry one-hour public cache hints; dynamic resource lists, runtime data, live account data, and conversations remain private and short-lived or uncached.
• Explicit conversation_id memory is application state and works independently of transport session state.

Migrating from 0.6.0

• The default model changed from deepseek-v4-flash to deepseek-flash.
• The MCP SDK moved from the monolithic v1 package to the split v2 packages.
• MCP_HTTP_STATEFUL_SESSION was removed. HTTP protocol handling is now per-request/stateless; use conversation_id for retained chat context.
• Four Files API tools and visual inputs were added.
• Existing tool names and include_raw_response behavior remain compatible.

Release 1.4.0

This release refreshes MCP dependencies, corrects Pro availability and Responses capabilities, adds apply_patch custom-tool results and FIM usage options, and fixes beta routing, end-to-end request deadlines, split CRLF SSE boundaries, stream error handling, and non-JSON provider errors. Existing tool names and opt-in raw responses are preserved. The complete API/MCP audit also adds vision request limits, complete Responses history, cancellation propagation, truthful capabilities, missing-resource errors, tool admission limits, reflected-credential redaction, and explicit remote HTTP authentication. DEEPSEEK_DEFAULT_MODEL is now honored by all three generation tools.

Earlier 1.1.0–1.3.0 version identifiers were historically published and removed; npm cannot reuse them. The next available minor release is 1.4.0.

Development and verification

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

Credentialed smoke tests:

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

The live smoke covers model listing, balance, text chat, thinking streaming, Responses, strict beta function calling, apply_patch custom-tool calls, FIM, visual input, and a Files upload/retrieve/list/delete lifecycle with cleanup.

Registry identity

• MCP Registry: io.github.DMontgomery40/deepseek
• npm: deepseek-mcp-server@1.4.0
• OCI: docker.io/dmontgomery40/deepseek-mcp-server:0.5.0 is the last published image and does not contain the current npm feature set.

Documentation audit

The release audit covers every supported DeepSeek endpoint reference and its current guides, plus all 31 pages and the authoritative schema of MCP 2026-07-28. Findings, coverage, source conflicts, optional capabilities, and verification limits are recorded in the API audit and the MCP audit. Anthropic-format provider APIs were read for context; this server exposes the OpenAI-compatible Chat, Responses, FIM, Files, model, and balance routes.

Official references

• DeepSeek changelog
• DeepSeek October 17 announcement
• DeepSeek Search and Fetch guide and billing
• DeepSeek Responses compatibility guide
• DeepSeek V4.1 Flash announcement
• DeepSeek pricing and model limits
• DeepSeek visual input guide
• DeepSeek Files API guide
• DeepSeek Chat Completions
• DeepSeek Responses API
• MCP 2026-07-28 specification
• MCP TypeScript SDK v2
• MCP SDK v2 migration guide

License

MIT