[DeepSeek MCP Server]
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.
[npm version]
[npm downloads]
[License: MIT]
[Node.js Version]
[TypeScript]
[DeepSeek V4.1]
[Build Status]
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.
[Official MCP Registry]
[LobeHub]
[Glama Badge]
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:
Cursor / Windsurf / VS Code:
Local (stdio)
Claude Code:
Gemini CLI:
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
Manual Installation
If you prefer to install manually:
From Source
- Clone the repository
- Install dependencies
- Build the project
Usage
Once configured, your MCP client will have access to deepseek_chat, deepseek_fim, and deepseek_sessions tools, plus 3 MCP resources.
Example prompts:
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:
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:
Reasoning Example (deepseek-flash with thinking enabled):
Thinking mode returns the chain-of-thought in <thinking> tags followed by the final answer.
DeepSeek V4 Pro Example (hardest tasks):
Function Calling Example:
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:
When thinking mode is enabled, temperature and top_p are automatically ignored.
JSON Output Mode Example:
JSON mode ensures the model outputs valid JSON. Include the word "json" in your prompt for best results. Supported by all models.
Schema-Validated JSON Example:
The server validates the parsed output against the schema. If it does not match, it retries up to RESPONSE_SCHEMA_MAX_RETRIES times (default 2), feeding the validation error back to the model, and returns the first schema-valid object. A persistent mismatch is surfaced as structuredContent.schema.valid = false rather than a silently coerced answer. Regex patterns in the schema are screened for catastrophic backtracking (ReDoS); an unsafe pattern is rejected up front as an invalid schema.
Multi-Turn Session Example:
Use the same session_id across requests to maintain conversation context. Messages are stored in memory and prepended automatically. In HTTP transport each connected MCP session has its own isolated session store — a session_id created by one HTTP client is not visible to another (see HTTP Transport below).
deepseek_fim
Fill-in-the-Middle completion. You give a prompt (the prefix) and an optional suffix, and the model completes the text in between. It is built for code completion and content infilling rather than conversation. FIM runs on DeepSeek's Beta endpoint in non-thinking mode, and the API caps output at 4096 tokens.
Parameters:
prompt (required): The prefix text before the gap. For code completion, this is the code up to the cursor.
suffix (optional): The text after the gap. The model fills the space between prompt and suffix.
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 (FIM has no thinking mode).
max_tokens (optional): Maximum tokens to generate, up to 4096.
temperature (optional): 0-2, controls randomness (default: 1.0).
stop (optional): A stop string or an array of up to 16 stop strings.
Response includes:
- The completion text
- Request information (tokens, model, cost in USD)
- Structured data with
text, usage, finish_reason, cost_usd and pricing_tier fields
Example (code completion):
The model returns the missing middle, e.g. fib(n-1) + fib(n-2), using both the prefix and the suffix as context. Available on both the npm/stdio server and the hosted worker endpoint.
deepseek_sessions
Manage conversation sessions.
Parameters:
action (required): "list" | "clear" | "delete"
session_id (optional): Required when action is "delete"
Examples:
Available Resources
MCP Resources provide read-only data about the server:
Model Fallback & Circuit Breaker
When a model fails with a retryable error (429, 503, timeout), the server automatically falls back to the other model:
deepseek-flash fails → tries deepseek-v4-pro
deepseek-v4-pro fails → tries deepseek-flash
The legacy names (which resolve to deepseek-flash) fall back to deepseek-v4-pro.
The circuit breaker protects against cascading failures:
- After
CIRCUIT_BREAKER_THRESHOLD consecutive failures (default: 5), the circuit opens (fast-fail mode)
- After
CIRCUIT_BREAKER_RESET_TIMEOUT ms (default: 30000), it enters half-open state and sends a probe request
- If the probe succeeds, the circuit closes and normal operation resumes
Fallback can be disabled with FALLBACK_ENABLED=false.
Available Prompts
Prompt templates (12 total):
Core Reasoning
- debug_with_reasoning: Debug code with step-by-step analysis
- code_review_deep: Comprehensive code review (security, performance, quality)
- research_synthesis: Research topics and create structured reports
- strategic_planning: Create strategic plans with reasoning
- explain_like_im_five: Explain complex topics in simple terms
Advanced
- mathematical_proof: Prove mathematical statements rigorously
- argument_validation: Analyze arguments for logical fallacies
- creative_ideation: Generate creative ideas with feasibility analysis
- cost_comparison: Compare LLM costs for tasks
- pair_programming: Interactive coding with explanations
Function Calling
- function_call_debug: Debug function calling issues with tool definitions and messages
- create_function_schema: Generate JSON Schema for function calling from natural language
Each prompt is optimized for thinking mode (deepseek-flash with thinking: {type: "enabled"}) to provide detailed reasoning.
Models
Both models have a 1M-token context window, up to 384K output tokens, and support function calling, JSON mode, and optional chain-of-thought thinking. They are non-thinking by default here for fast responses; enable reasoning with thinking: {type: "enabled"}.
DeepSeek bills by time of day. Peak is 01:00-04:00 and 06:00-10:00 UTC, Monday to Friday, and costs twice the off-peak rate; every other hour, including weekends, is off-peak. The cost this server reports uses whichever rate applied when the request ran. Prices below are USD per 1M tokens, from DeepSeek's pricing page as of 2026-10-23.
deepseek-flash (default)
- Model: DeepSeek-V4.1-Flash-1017
- Best for: General conversations, coding, content generation, agent loops
- Context: 1M tokens
- Max Output: 384K tokens
- Off-peak: $0.003 cache hit, $0.15 cache miss, $0.60 output
- Peak: $0.006 cache hit, $0.30 cache miss, $1.20 output
deepseek-v4-pro
- Model: DeepSeek-V4-Pro-0813
- Best for: Hard multi-step tasks where you want the larger model
- Context: 1M tokens
- Max Output: 384K tokens
- Off-peak: $0.022 cache hit, $0.66 cache miss, $1.98 output
- Peak: $0.044 cache hit, $1.32 cache miss, $3.96 output
DeepSeek's own benchmarks put V4.1 Flash ahead of V4 Pro, so Flash is the better default for most work.
Legacy names
deepseek-v4-flash, deepseek-chat and deepseek-reasoner are still accepted and resolve to deepseek-flash (chat = non-thinking, reasoner = thinking). DeepSeek retired the models behind them and serves those names with V4.1 Flash anyway, so this server sends deepseek-flash on the wire. deepseek-chat and deepseek-reasoner will be removed in the next major release. New setups should use deepseek-flash or deepseek-v4-pro.
Configuration
The server is configured via environment variables. All settings except DEEPSEEK_API_KEY are optional.
Example with custom config:
Development
Project Structure
Building
Watch Mode (for development)
Testing
Testing Locally
The server will start and wait for MCP client connections via stdio.
Remote Endpoint (Hosted)
A hosted BYOK (Bring Your Own Key) endpoint is available at:
Send your DeepSeek API key as Authorization: Bearer <key>. No server-side API key stored — your key is used directly per request. Powered by Cloudflare Workers (global edge, zero cold start).
Note: Thinking mode may take over 30 seconds for complex queries. Some MCP clients (e.g. Claude Code) have built-in tool call timeouts that may interrupt long-running requests. When latency matters, the default non-thinking mode is recommended.
HTTP Transport (Self-Hosted)
Run your own HTTP endpoint:
Test the health endpoint:
The MCP endpoint is available at POST /mcp (Streamable HTTP protocol).
Securing the endpoint (read before exposing it). In self-hosted HTTP mode the
server holds your DEEPSEEK_API_KEY and uses it for every deepseek_chat call.
Anyone who can reach POST /mcp can invoke tools and spend that key, so the
endpoint must not sit open on a public interface. The defaults are built around
this:
HTTP_HOST defaults to 127.0.0.1, so a plain run only listens on loopback and the SDK's DNS rebinding protection is active. Nothing off the machine can reach it.
- To accept remote connections, set
HTTP_HOST=0.0.0.0 and either HTTP_AUTH_TOKEN (so /mcp requires Authorization: Bearer <token>) or HTTP_ALLOWED_HOSTS. Binding 0.0.0.0 with neither turns the SDK's Host-header check off entirely, which leaves /mcp open to DNS rebinding from any web page you visit, so the server refuses to start rather than warn. HTTP_ALLOW_UNPROTECTED_BIND=true overrides the refusal if you really want an open endpoint.
- For an internet-facing deployment, put an authenticating reverse proxy with TLS in front and set
HTTP_ALLOWED_HOSTS to your real hostname(s).
HTTP_AUTH_TOKEN is a static gateway token for the self-hosted endpoint and is
unrelated to your DeepSeek key. It is separate from the hosted BYOK endpoint
above, where clients pass their own DeepSeek key as the bearer.
Session isolation (1.7.0+): In HTTP transport each connected MCP session
gets its own McpServer instance and its own SessionStore. Conversation
history, session listings, and deletions are scoped to the MCP session that
created them, so one client cannot read, enumerate, or wipe another client's
sessions. STDIO transport is single-tenant by nature and unaffected.
Docker
The image runs HTTP transport on port 3000 with a health check. Inside the
container it binds 0.0.0.0 (required for the port mapping to work), so control
exposure at the publish layer: the example above and the bundled
docker-compose.yml publish to 127.0.0.1 only.
Publishing on loopback is not on its own enough, because DNS rebinding targets
the loopback address your own browser can already reach. The image therefore
ships HTTP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1], which keeps the Host
check installed. Publishing under a real hostname? Add it to that list, or every
request carrying it gets a 403. Publishing on a public interface? Set
HTTP_AUTH_TOKEN as well.
Troubleshooting
"DEEPSEEK_API_KEY environment variable is not set"
Option 1: Use the correct installation command
Option 2: Manually edit the config file
If you already installed without the API key, edit your config file:
- For Claude Code: Open
~/.claude.json (Windows: C:\Users\USERNAME\.claude.json)
- Find the
"mcpServers" section under your project path
- Add the
env field with your API key:
- Save and restart Claude Code
"Failed to connect to DeepSeek API"
- Check your API key is valid
- Verify you have internet connection
- Check DeepSeek API status at https://status.deepseek.com
Server not appearing in your MCP client
- Verify the path to
dist/index.js is correct
- Make sure you ran
npm run build
- Check your MCP client's logs for errors
- Restart your MCP client completely
Permission Denied on macOS/Linux
Make the file executable:
Publishing to npm
To share this MCP server with others:
- Run
npm login
- Run
npm publish --access public
Users can then install with:
Contributing
Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.
Reporting Issues
Found a bug or have a feature request? Please open an issue using our templates.
Development
Changelog
See CHANGELOG.md for version history and updates.
License
MIT License - see LICENSE file for details
Support
Resources
Acknowledgments
Made by @arikusi
An independent, community-maintained MCP server for the DeepSeek API.