DeepSeek MCP Server

The deepseek-mcp-server@1.0.1 modernization aims to introduce multimodal capabilities (DeepSeek V4.1 Flash visual input), a Files API toolset, and support for dual-era MCP transports (2026 protocol and legacy).

Architecturally, the server extends the DeepSeek fetch client with typed multimodal JSON and multipart Files API operations, exposing them via the MCP server factory. It transitions from MCP SDK v1 to the stable v2 split packages, utilizing serveStdio and createMcpHandler to decouple application state (conversation handles) from stateless protocol transport.

As of version 1.0.1, the server has updated its model defaults to align with current DeepSeek contracts:

• Canonical Model: deepseek-flash (DeepSeek V4.1 Flash) is the default model used everywhere user-facing defaults are declared.
• Legacy Aliases: Names like deepseek-v4-flash and deepseek-v4-flash-vision-exp are retired and temporarily route to deepseek-flash.
• Pro Models: deepseek-v4-pro is still accepted but is scheduled to route to V4.1 Flash starting 2026-09-14 until V4.1 Pro is released.

The chat_completion and create_response tools support typed image inputs, allowing you to send visual data alongside text.

Supported Image Sources

• HTTPS URLs: Direct links to images.
• Base64 Data URLs: Images encoded as data URLs.
• Files API file_id: References to files previously uploaded via the upload_file tool.

Image Configuration

When providing an image URL, you can specify a detail level:

• low
• high
• original
• auto

Chat Content Structure

The chat_completion.message field has been expanded. It now accepts either a simple string (for backward compatibility) or an array of typed content parts (including text, image URL parts, and file parts).

The DeepSeek MCP server supports various visual and file inputs for multimodal requests. When constructing requests, ensure you are using one of the following supported formats:

• Plain text: Standard text-based chat.
• Chat image/file sources: Valid image or file sources for Chat completions.
• Responses image placement: Specific image placements within the Responses API.
• Upload formats:
  • Raw base64 encoded data.
  • Supported image data URLs.

Note that the server validates these inputs for malformed base64, unsupported media types, and invalid file IDs.

To run or develop with the modernized DeepSeek MCP server, ensure your environment meets the following specifications:

• Runtime: Node.js 20+
• Language: TypeScript 6
• Validation: Zod 4
• Testing: Vitest 5
• SDK: MCP TypeScript SDK v2
• Web APIs: Native fetch, FormData, and Blob support.

To ensure the server is built correctly and passes all internal quality gates, run the following verification commands in your development environment:

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

If you have valid DeepSeek credentials configured and wish to perform live smoke testing (covering model listing, balance, text chat, thinking streaming, visual requests, and Files CRUD operations), use:

npm run test:live
npm run test:remote

You can run the server as a local HTTP endpoint instead of using stdio. This is useful for browser-based clients.

Start the server

Set MCP_TRANSPORT=streamable-http and specify the host and port.

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.

Handling CORS/Origins

If using a browser client, you must explicitly allow the origin using MCP_HTTP_ALLOWED_ORIGINS. Requests with an Origin header that are not in the allowlist will be rejected with a 403 error.

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

The server provides tools to manage reusable image inputs via the DeepSeek Files API.

Upload a file

Use upload_file to upload base64 JPEG, PNG, GIF, or WebP data. This returns a file_id.

Safety Constraints:

• Does not accept local file paths or arbitrary URLs.
• Decoded uploads are limited to 64 MiB.
• expires_after_seconds must be between 3,600 and 2,592,000 seconds.

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

File Lifecycle Tools

• list_files: List uploaded files (supports cursor, order, and purpose filters).
• retrieve_file: Retrieve metadata for a specific file_id.
• delete_file: Delete a specific uploaded file.

The DeepSeek MCP Server requires Node.js 20 or newer. You can install and run it via stdio using npx, or integrate it into specific MCP clients like Codex CLI or Claude Code.

Run via 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

Manual MCP Client Configuration

If configuring a client manually, use the following JSON structure:

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

If you are upgrading from version 0.6.0 to 1.0.1, note the following breaking changes and improvements:

• Removed Configuration: The MCP_HTTP_STATEFUL_SESSION environment variable/configuration has been removed. The server now uses modern protocol negotiation.
• New Tools: You now have access to the Files API tools (upload_file, list_files, retrieve_file, delete_file).
• Protocol Upgrade: The server now supports MCP SDK v2 and the 2026 protocol. Clients should use versionNegotiation: { mode: "auto" } to ensure compatibility.
• Multimodality Clarification: DeepSeek multimodality in this server is strictly for visual input. It does not support image generation, video, or audio input/output.