Deepseek

DeepSeek MCP Server

MCP server for DeepSeek (deepseek-flash and deepseek-v4-pro, 1M context) with multi-turn sessions, function calling, thinking mode, and peak-aware cost tracking.

Compatible with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible client.

Officially listed on the MCP Registry , Smithery , Glama , LobeHub , and Fronteir AI .

2.4.0 follows DeepSeek's V4.1 rename. The default model is now deepseek-flash (V4.1 Flash), next to deepseek-v4-pro. Both have a 1M-token context window and optional chain-of-thought thinking. deepseek-v4-flash, deepseek-chat and deepseek-reasoner keep working as legacy names and are sent as deepseek-flash, so existing configs need no change.

Quick Start

Remote (No Install)

Use the hosted endpoint directly — no npm install, no Node.js required. Bring your own DeepSeek API key:

Claude Code:

claude mcp add --transport http deepseek \

https://deepseek-mcp.tahirl.com/mcp \ --header "Authorization: Bearer YOUR_DEEPSEEK_API_KEY"

Cursor / Windsurf / VS Code:

{

"mcpServers": { "deepseek": { "url": "https://deepseek-mcp.tahirl.com/mcp", "headers": { "Authorization": "Bearer ${DEEPSEEK_API_KEY}" } } } }

Local (stdio)

Claude Code:

claude mcp add -s user deepseek npx @arikusi/deepseek-mcp-server -e DEEPSEEK_API_KEY=your-key-here

Gemini CLI:

gemini mcp add deepseek npx @arikusi/deepseek-mcp-server -e DEEPSEEK_API_KEY=your-key-here

Scope options (Claude Code):

• -s user: Available in all your projects (recommended)
• -s local: Only in current project (default)
• -s project: Project-specific .mcp.json file

Get your API key: https://platform.deepseek.com

---

Features

• DeepSeek V4.1 Flash and V4 Pro: deepseek-flash and deepseek-v4-pro, both with 1M context and optional chain-of-thought thinking mode
• Multi-Turn Sessions: Conversation context preserved across requests via session_id parameter
• Model Fallback & Circuit Breaker: Automatic fallback between models with circuit breaker protection against cascading failures
• MCP Resources: deepseek://models, deepseek://config, deepseek://usage — query model info, config, and usage stats
• Thinking Mode: Enable chain-of-thought reasoning on either model with thinking: {type: "enabled"}
• JSON Output Mode: Structured JSON responses with json_mode: true
• Schema-Validated JSON: Pass a response_schema and the server validates the output against it, with bounded repair retries and a ReDoS guard on schema patterns
• Function Calling: OpenAI-compatible tool use with up to 128 tool definitions
• Fill-in-the-Middle (FIM): Code and content completion between a prefix and suffix via the deepseek_fim tool
• Cache-Aware Cost Tracking: Automatic cost calculation with cache hit/miss breakdown, priced at the peak or off-peak rate that applied when the request ran
• Session Management Tool: List, delete, and clear sessions via deepseek_sessions tool
• Configurable: Environment-based configuration with validation
• 12 Prompt Templates: Templates for debugging, code review, function calling, and more
• Streaming Support: Real-time response generation
• Multimodal Ready: Content part types for text + image input (enable with ENABLE_MULTIMODAL=true)
• Remote Endpoint: Hosted at deepseek-mcp.tahirl.com/mcp — BYOK (Bring Your Own Key), no install needed
• HTTP Transport: Self-hosted remote access via Streamable HTTP with TRANSPORT=http
• Docker Ready: Multi-stage Dockerfile with health checks for containerized deployment
• Tested: 368 tests, ~92% line coverage
• Type-Safe: Full TypeScript implementation
• MCP Compatible: Works with any MCP-compatible CLI (Claude Code, Gemini CLI, etc.)

Installation

Prerequisites

• Node.js 22+
• A DeepSeek API key (get one at https://platform.deepseek.com)

Manual Installation

If you prefer to install manually:

npm install -g @arikusi/deepseek-mcp-server

From Source

1. Clone the repository

git clone https://github.com/arikusi/deepseek-mcp-server.git

cd deepseek-mcp-server

1. Install dependencies

npm install

1. Build the project

npm run build

Usage

Once configured, your MCP client will have access to deepseek_chat, deepseek_fim, and deepseek_sessions tools, plus 3 MCP resources.

Example prompts:

"Use DeepSeek to explain quantum computing"

"Ask DeepSeek Reasoner to solve: If I have 10 apples and buy 5 more..."

Your MCP client will automatically call the deepseek_chat tool.

Manual Configuration (Advanced)

If your MCP client doesn't support the add command, manually add to your config file:

{

"mcpServers": { "deepseek": { "command": "npx", "args": ["@arikusi/deepseek-mcp-server"], "env": { "DEEPSEEK_API_KEY": "your-api-key-here" } } } }

Config file locations:

• Claude Code: ~/.claude.json (add to projects["your-project-path"].mcpServers section)
• Other MCP clients: Check your client's documentation for config file location

Available Tools

deepseek_chat

Chat with DeepSeek AI models with automatic cost tracking and function calling support.

Parameters:

• messages (required): Array of conversation messages
• role: "system" | "user" | "assistant" | "tool"
• content: Message text
• tool_call_id (optional): Required for tool role messages
• model (optional): "deepseek-flash" (default) or "deepseek-v4-pro". The legacy names "deepseek-v4-flash", "deepseek-chat" and "deepseek-reasoner" are still accepted and resolve to deepseek-flash (reasoner always thinks); prefer "deepseek-flash".
• temperature (optional): 0-2, controls randomness (default: 1.0). Ignored when thinking mode is enabled.
• max_tokens (optional): Maximum tokens to generate (both models support up to 384000)
• stream (optional): Enable streaming mode (default: false)
• tools (optional): Array of tool definitions for function calling (max 128)
• tool_choice (optional): "auto" | "none" | "required" | {type: "function", function: {name: "..."}}
• thinking (optional): Toggle thinking mode, {type: "enabled"} to reason or {type: "disabled"} for a fast answer (non-thinking is the default)
• reasoning_effort (optional): "low", "high" (default) or "max", applies only while thinking mode is active
• json_mode (optional): Enable JSON output mode (supported by both models)
• response_schema (optional): A JSON Schema to validate the model output against. Implies JSON output. The server validates the parsed result and, on failure, issues up to RESPONSE_SCHEMA_MAX_RETRIES repair retries (default 2, set 0 to disable) that feed the validation error back to the model. Schema regex patterns are screened for ReDoS and an unsafe pattern is rejected up front.
• session_id (optional): Session ID for multi-turn conversations. Previous context is automatically prepended.

Response includes:

• Content with formatting (recovered as clean JSON when JSON output is requested)
• Function call results (if tools were used)
• Request information (tokens, model, cost in USD)
• structuredContent.request: a self-contained per-request usage and cost summary (token counts, cache hit/miss, cost_usd, and the pricing_tier it was priced at), aggregated across any repair retries
• structuredContent.effective and fallback: what was actually sent after alias/thinking resolution, and any silent model fallback that fired
• structuredContent.schema: when response_schema is used, {valid, attempts, error?}; json_parse_error when JSON output could not be recovered

Example:

{

"messages": [ { "role": "user", "content": "Explain the theory of relativity in simple terms" } ], "model": "deepseek-flash", "temperature": 0.7, "max_tokens": 1000 }

Reasoning Example (deepseek-flash with thinking enabled):

{

"messages": [ { "role": "user", "content": "If I have 10 apples and eat 3, then buy 5 more, how many do I have?" } ], "model": "deepseek-flash", "thinking": { "type": "enabled" } }

Thinking mode returns the chain-of-thought in tags followed by the final answer.

DeepSeek V4 Pro Example (hardest tasks):

{

"messages": [ { "role": "user", "content": "Prove that the square root of 2 is irrational." } ], "model": "deepseek-v4-pro", "thinking": { "type": "enabled" } }

Function Calling Example:

{

"messages": [ { "role": "user", "content": "What's the weather in Istanbul?" } ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City name" } }, "required": ["location"] } } } ], "tool_choice": "auto" }

When the model decides to call a function, the response includes tool_calls with the function name and arguments. You can then send the result back using a tool role message with the matching tool_call_id.

Thinking Mode Example:

{

"messages": [ { "role": "user", "content": "Analyze the time complexity of quicksort" } ], "model": "deepseek-flash", "thinking"