DeepSeek MCP Server is an MCP (Model Context Protocol) server for DeepSeek V4, providing MCP-compatible clients with chat, reasoning, function calling, thinking mode, and cost tracking capabilities.
Main Capabilities
Model Support: v2.0.0 is based on DeepSeek V4, offering two models: deepseek-v4-flash (fast and economical) and deepseek-v4-pro (most capable), both featuring a 1M token context window and an optional chain-of-thought thinking mode. The original deepseek-chat and deepseek-reasoner configurations remain available via deprecated aliases, upgraded as drop-in replacements, but new configurations should use the V4 names.
Multi-turn Sessions: Preserve conversation context between requests via the session_id parameter.
Model Fallback and Circuit Breaking: Automatically fall back to another model when a model encounters retryable errors (429, 503, timeouts), with circuit-breaker protection to prevent cascading failures.
MCP Resources: Provide deepseek://models, deepseek://config, deepseek://usage for querying model information, configuration, and usage statistics.
Thinking Mode: Enable chain-of-thought reasoning on any V4 model via thinking: {type: "enabled"}.
JSON Output Mode: Obtain structured JSON responses via json_mode: true.
Schema-Validated JSON: When response_schema is passed in, the server validates the output, with bounded repair retries and ReDoS protection for schema patterns.
Function Calling: OpenAI-compatible tool use, supporting up to 128 tool definitions.
Fill-in-the-Middle (FIM): Complete code and content between prefixes and suffixes via the deepseek_fim tool.
Cache-Aware Cost Tracking: Automatically calculate costs, with cache hit/miss breakdowns.
Session Management Tools: List, delete, and clear sessions via the deepseek_sessions tool.
Other Features: Environment-variable-based configurability and validation, 12 prompt templates, streaming responses, multimodal readiness (enable text+image input via ENABLE_MULTIMODAL=true), remote endpoints, HTTP transport, Docker readiness, 340 tests with approximately 92% line coverage, fully TypeScript type-safe implementation.
Usage
Remote Usage (No Installation Required): Use the hosted endpoint directly, with no npm install or Node.js needed, just bring your own DeepSeek API key. Suitable for Cursor / Windsurf / VS Code. Claude Code offers three scope options: -s user, -s local, -s project. API key acquisition address:https://platform.deepseek.com。
Manual installation: Clone the repository, install dependencies, build the project. After configuration is complete, the MCP client can use the deepseek_chat, deepseek_fim, and deepseek_sessions tools, as well as 3 MCP resources.
Manual configuration (advanced): If the client does not support the add command, you can manually add it to the configuration file. Claude Code's configuration file is located at ~/.claude.json (add it to the projects["your-project-path"].mcpServers section); for other MCP clients, please consult their documentation.
Available tools
deepseek_chat: Chat with DeepSeek AI models, with support for automatic cost tracking and function calling. Parameters include messages (required, containing role, content, tool_call_id), model, temperature, max_tokens, stream, tools, tool_choice, thinking, reasoning_effort, json_mode, response_schema, session_id. The response includes formatted content, function call results, request information (tokens, model, dollar cost), and fields such as request, effective, fallback, schema under structuredContent.
deepseek_fim: Fill-in-the-Middle completion, used for code completion and content filling rather than conversation, runs on the DeepSeek Beta endpoint, in non-thinking mode, with an API output limit of 4096 tokens. Parameters include prompt (required), suffix, model, max_tokens, temperature, stop.
deepseek_sessions: Manage sessions; action supports list, clear, delete; delete requires session_id.
Model capabilities and pricing
Both V4 models have a 1M token context window, up to 384K output tokens, support function calling, JSON mode, and optional chain-of-thought, and default to non-thinking mode forfast responses.
deepseek-v4-flash (default): suitable for general conversation, coding, content generation, agent loops; fast and economical; pricing is $0.0028/1M for cache hits, $0.14/1M for cache misses, and $0.28/1M for output.
deepseek-v4-pro: suitable for complex reasoning, mathematics, difficult multi-step tasks, and the highest-quality output; slower than flash, with the highest capability; pricing is $0.003625/1M for cache hits, $0.435/1M for cache misses, and $0.87/1M for output.
The deprecated aliases deepseek-chat and deepseek-reasoner are still accepted and resolve to deepseek-v4-flash's non-thinking/thinking modes respectively, and will be removed in the next major release. The DeepSeek API itself discontinued these two names on 2026-07-24.
Fallback and circuit breaker mechanism
When a model encounters a retryable error, it automatically falls back: if deepseek-v4-flash fails, it tries deepseek-v4-pro, and vice versa. After consecutive failures reach the threshold (5 by default), the circuit breaker enters fast-fail mode, waits CIRCUIT_BREAKER_RESET_TIMEOUT milliseconds (30000 by default), then enters the half-open state and sends a probe request; if successful, it closes the circuit breaker and returns to normal. Fallback can be disabled via FALLBACK_ENABLED=false.
Prompt templates
12 built-in templates: debug_with_reasoning, code_review_deep, research_synthesis, strategic_planning, explain_like_im_five, mathematical_proof, argument_validation, creative_ideation, cost_comparison, pair_programming, function_call_debug, create_function_schema. Each template is optimized for thinking mode.
Deployment and configuration
Configure through environment variables; all are optional except DEEPSEEK_API_KEY.
Remote endpoint (hosted): Provides the BYOK endpoint deepseek-mcp.tahirl.com/mcp, send the DeepSeek API key via Authorization: Bearer <key>. The server does not store the key and is powered by Cloudflare Workers (global edge, zero cold start). Note that thinking mode may exceed 30 seconds for complex queries, and some MCP clients (such as Claude Code) have built-in tool call timeouts that may interrupt long requests.
HTTP transport (self-hosted): You can run your own HTTP endpoint, with the MCP endpoint at POST /mcp (Streamable HTTP protocol). In self-hosted HTTP mode, the server holds DEEPSEEK_API_KEY and uses it for every deepseek_chat call; anyone who can access POST /mcp can invoke the tool and consume that key. HTTP_HOST defaults to 127.0.0.1, listening only on loopback, and the SDK's DNS rebinding protection takes effect. To accept remote connections, set HTTP_HOST=0.0.0.0 and configure HTTP_AUTH_TOKEN or HTTP_ALLOWED_HOSTS. Binding only to 0.0.0.0 without configuring either disables the SDK's Host header check, exposing /mcp to DNS rebinding risk, and the server will refuse to start that way.
Use cases
Suitable for developers and users who need to integrate DeepSeek V4 chat and reasoning capabilities into MCP-compatible clients (such as Claude Code, Gemini CLI, Cursor, Windsurf), supporting scenarios such as multi-turn conversation, function calling, code completion, structured output, and cost tracking.
