Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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

MCP Server for DeepSeek API - enables MCP clients to use DeepSeek Chat and Reasoner models
https://github.com/arikusi/deepseek-mcp-server

ai claude-code deepseek gemini-cli llm mcp mcp-server typescript

Last synced: 4 months ago
JSON representation

MCP Server for DeepSeek API - enables MCP clients to use DeepSeek Chat and Reasoner models

Awesome Lists containing this project

README 

          
# DeepSeek MCP Server



[![npm version](https://img.shields.io/npm/v/@arikusi/deepseek-mcp-server.svg)](https://www.npmjs.com/package/@arikusi/deepseek-mcp-server)

[![npm downloads](https://img.shields.io/npm/dm/@arikusi/deepseek-mcp-server.svg)](https://www.npmjs.com/package/@arikusi/deepseek-mcp-server)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Node.js Version](https://img.shields.io/node/v/@arikusi/deepseek-mcp-server.svg)](https://nodejs.org/)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)

[![Build Status](https://github.com/arikusi/deepseek-mcp-server/workflows/CI/badge.svg)](https://github.com/arikusi/deepseek-mcp-server/actions)



A Model Context Protocol (MCP) server that integrates DeepSeek AI models with MCP-compatible clients. Access DeepSeek's powerful chat and reasoning models with multi-turn sessions, automatic model fallback, and MCP Resources directly from your development environment.



**Compatible with:**

- Claude Code CLI

- Gemini CLI

- Any MCP-compatible client (Cursor, Windsurf, etc.)



> **Note**: This is an unofficial community project and is not affiliated with DeepSeek.



## Quick Start



### For Claude Code



```bash

# Install and configure with API key (available in all projects)

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



# Or install for current project only

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

```



**Scope options:**

- `-s user`: Available in all your projects (recommended)

- `-s local`: Only in current project (default)

- `-s project`: Project-specific `.mcp.json` file



### For Gemini CLI



```bash

# Install and configure with API key

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

```



**Get your API key:** [https://platform.deepseek.com](https://platform.deepseek.com)



That's it! Your MCP client can now use DeepSeek models!



---



## Features



- **DeepSeek V3.2**: Both models now run DeepSeek-V3.2 (since Sept 2025)

- **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 enhanced reasoning on deepseek-chat with `thinking: {type: "enabled"}`

- **JSON Output Mode**: Structured JSON responses with `json_mode: true`

- **Function Calling**: OpenAI-compatible tool use with up to 128 tool definitions

- **Cache-Aware Cost Tracking**: Automatic cost calculation with cache hit/miss breakdown

- **Session Management Tool**: List, delete, and clear sessions via `deepseek_sessions` tool

- **Configurable**: Environment-based configuration with validation

- **12 Prompt Templates**: Pre-built templates for debugging, code review, function calling, and more

- **Streaming Support**: Real-time response generation

- **Tested**: 198 tests with 90%+ code coverage

- **Type-Safe**: Full TypeScript implementation

- **MCP Compatible**: Works with any MCP-compatible CLI (Claude Code, Gemini CLI, etc.)



## Installation



### Prerequisites



- Node.js 18+

- A DeepSeek API key (get one at [https://platform.deepseek.com](https://platform.deepseek.com))



### Manual Installation



If you prefer to install manually:



```bash

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

```



### From Source



1. **Clone the repository**



```bash

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

cd deepseek-mcp-server

```



2. **Install dependencies**



```bash

npm install

```



3. **Build the project**



```bash

npm run build

```



## Usage



Once configured, your MCP client will have access to `deepseek_chat` 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:



```json

{

  "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-chat" (default) or "deepseek-reasoner"

- `temperature` (optional): 0-2, controls randomness (default: 1.0). Ignored when thinking mode is enabled.

- `max_tokens` (optional): Maximum tokens to generate (deepseek-chat: max 8192, deepseek-reasoner: max 65536)

- `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): Enable thinking mode `{type: "enabled"}` for enhanced reasoning

- `json_mode` (optional): Enable JSON output mode (supported by both models)

- `session_id` (optional): Session ID for multi-turn conversations. Previous context is automatically prepended.



**Response includes:**

- Content with formatting

- Function call results (if tools were used)

- Request information (tokens, model, cost in USD)

- Structured data with `cost_usd` and `tool_calls` fields



**Example:**



```json

{

  "messages": [

    {

      "role": "user",

      "content": "Explain the theory of relativity in simple terms"

    }

  ],

  "model": "deepseek-chat",

  "temperature": 0.7,

  "max_tokens": 1000

}

```



**DeepSeek Reasoner Example:**



```json

{

  "messages": [

    {

      "role": "user",

      "content": "If I have 10 apples and eat 3, then buy 5 more, how many do I have?"

    }

  ],

  "model": "deepseek-reasoner"

}

```



The reasoner model will show its thinking process in `` tags followed by the final answer.



**Function Calling Example:**



```json

{

  "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:**



```json

{

  "messages": [

    {

      "role": "user",

      "content": "Analyze the time complexity of quicksort"

    }

  ],

  "model": "deepseek-chat",

  "thinking": { "type": "enabled" }

}

```



When thinking mode is enabled, `temperature`, `top_p`, `frequency_penalty`, and `presence_penalty` are automatically ignored. The model provides enhanced reasoning capabilities similar to deepseek-reasoner.



**JSON Output Mode Example:**



```json

{

  "messages": [

    {

      "role": "user",

      "content": "Return a json object with name, age, and city fields for a sample user"

    }

  ],

  "model": "deepseek-chat",

  "json_mode": true

}

```



JSON mode ensures the model outputs valid JSON. Include the word "json" in your prompt for best results. Supported by both `deepseek-chat` and `deepseek-reasoner`.



**Multi-Turn Session Example:**



```json

{

  "messages": [

    {

      "role": "user",

      "content": "What is the capital of France?"

    }

  ],

  "session_id": "my-session-1"

}

```



Use the same `session_id` across requests to maintain conversation context. The server stores messages in memory and automatically prepends history to each request.



### `deepseek_sessions`



Manage conversation sessions.



**Parameters:**

- `action` (required): "list" | "clear" | "delete"

- `session_id` (optional): Required when action is "delete"



**Examples:**

```json

{"action": "list"}

{"action": "delete", "session_id": "my-session-1"}

{"action": "clear"}

```



## Available Resources



MCP Resources provide read-only data about the server:



| Resource URI | Description |

|-------------|-------------|

| `deepseek://models` | Available models with capabilities, context limits, and pricing |

| `deepseek://config` | Current server configuration (API key masked) |

| `deepseek://usage` | Real-time usage statistics (requests, tokens, costs, sessions) |



## 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-chat` fails → tries `deepseek-reasoner`

- `deepseek-reasoner` fails → tries `deepseek-chat`



The circuit breaker protects against cascading failures:

- After 5 consecutive failures, the circuit **opens** (fast-fail mode)

- After 30 seconds, 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



Pre-built prompt templates for common tasks (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 the DeepSeek Reasoner model to provide detailed reasoning.



## Models



Both models run **DeepSeek-V3.2** with unified pricing.



### deepseek-chat



- **Best for**: General conversations, coding, content generation

- **Speed**: Fast

- **Context**: 128K tokens

- **Max Output**: 8K tokens (default 4K)

- **Mode**: Non-thinking (can enable thinking via parameter)

- **Features**: Thinking mode, JSON mode, function calling, FIM completion

- **Pricing**: $0.028/1M cache hit, $0.28/1M cache miss, $0.42/1M output



### deepseek-reasoner



- **Best for**: Complex reasoning, math, logic problems, multi-step tasks

- **Speed**: Slower (shows thinking process)

- **Context**: 128K tokens

- **Max Output**: 64K tokens (default 32K)

- **Mode**: Thinking (always active, chain-of-thought reasoning)

- **Features**: JSON mode, function calling

- **Output**: Both reasoning process and final answer

- **Pricing**: $0.028/1M cache hit, $0.28/1M cache miss, $0.42/1M output



## Configuration



The server is configured via environment variables. All settings except `DEEPSEEK_API_KEY` are optional.



| Variable | Default | Description |

|----------|---------|-------------|

| `DEEPSEEK_API_KEY` | (required) | Your DeepSeek API key |

| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | Custom API endpoint |

| `DEFAULT_MODEL` | `deepseek-chat` | Default model for requests |

| `SHOW_COST_INFO` | `true` | Show cost info in responses |

| `REQUEST_TIMEOUT` | `60000` | Request timeout in milliseconds |

| `MAX_RETRIES` | `2` | Maximum retry count for failed requests |

| `SKIP_CONNECTION_TEST` | `false` | Skip startup API connection test |

| `MAX_MESSAGE_LENGTH` | `100000` | Maximum message content length (characters) |

| `SESSION_TTL_MINUTES` | `30` | Session time-to-live in minutes |

| `MAX_SESSIONS` | `100` | Maximum number of concurrent sessions |

| `FALLBACK_ENABLED` | `true` | Enable automatic model fallback on errors |



**Example with custom config:**

```bash

claude mcp add -s user deepseek npx @arikusi/deepseek-mcp-server \

  -e DEEPSEEK_API_KEY=your-key \

  -e SHOW_COST_INFO=false \

  -e REQUEST_TIMEOUT=30000

```



## Development



### Project Structure



```

deepseek-mcp-server/

├── src/

│   ├── index.ts              # Entry point, bootstrap

│   ├── server.ts             # McpServer factory (auto-version)

│   ├── deepseek-client.ts    # DeepSeek API wrapper (circuit breaker + fallback)

│   ├── config.ts             # Centralized config with Zod validation

│   ├── cost.ts               # Cost calculation and formatting

│   ├── schemas.ts            # Zod input validation schemas

│   ├── types.ts              # TypeScript types + type guards

│   ├── errors.ts             # Custom error classes

│   ├── session.ts            # In-memory session store (multi-turn)

│   ├── circuit-breaker.ts    # Circuit breaker pattern

│   ├── usage-tracker.ts      # Usage statistics tracker

│   ├── tools/

│   │   ├── deepseek-chat.ts  # deepseek_chat tool (sessions + fallback)

│   │   ├── deepseek-sessions.ts # deepseek_sessions tool

│   │   └── index.ts          # Tool registration aggregator

│   ├── resources/

│   │   ├── models.ts         # deepseek://models resource

│   │   ├── config.ts         # deepseek://config resource

│   │   ├── usage.ts          # deepseek://usage resource

│   │   └── index.ts          # Resource registration aggregator

│   └── prompts/

│       ├── core.ts           # 5 core reasoning prompts

│       ├── advanced.ts       # 5 advanced prompts

│       ├── function-calling.ts # 2 function calling prompts

│       └── index.ts          # Prompt registration aggregator

├── dist/                     # Compiled JavaScript

├── llms.txt                  # AI discoverability index

├── llms-full.txt             # Full docs for LLM context

├── vitest.config.ts          # Test configuration

├── package.json

├── tsconfig.json

└── README.md

```



### Building



```bash

npm run build

```



### Watch Mode (for development)



```bash

npm run watch

```



### Testing



```bash

# Run all tests

npm test



# Watch mode

npm run test:watch



# With coverage report

npm run test:coverage

```



### Testing Locally



```bash

# Set API key

export DEEPSEEK_API_KEY="your-key"



# Run the server

npm start

```



The server will start and wait for MCP client connections via stdio.



## Troubleshooting



### "DEEPSEEK_API_KEY environment variable is not set"



**Option 1: Use the correct installation command**

```bash

# Make sure to include -e flag with your API key

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

```



**Option 2: Manually edit the config file**



If you already installed without the API key, edit your config file:



1. **For Claude Code**: Open `~/.claude.json` (Windows: `C:\Users\USERNAME\.claude.json`)

2. Find the `"mcpServers"` section under your project path

3. Add the `env` field with your API key:

```json

"deepseek": {

  "type": "stdio",

  "command": "npx",

  "args": ["@arikusi/deepseek-mcp-server"],

  "env": {

    "DEEPSEEK_API_KEY": "your-api-key-here"

  }

}

```

4. Save and restart Claude Code



### "Failed to connect to DeepSeek API"



1. Check your API key is valid

2. Verify you have internet connection

3. Check DeepSeek API status at [https://status.deepseek.com](https://status.deepseek.com)



### Server not appearing in your MCP client



1. Verify the path to `dist/index.js` is correct

2. Make sure you ran `npm run build`

3. Check your MCP client's logs for errors

4. Restart your MCP client completely



### Permission Denied on macOS/Linux



Make the file executable:



```bash

chmod +x dist/index.js

```



## Publishing to npm



To share this MCP server with others:



1. Run `npm login`

2. Run `npm publish --access public`



Users can then install with:



```bash

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

```



## Contributing



Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting PRs.



### Reporting Issues



Found a bug or have a feature request? Please [open an issue](https://github.com/arikusi/deepseek-mcp-server/issues/new/choose) using our templates.



### Development



```bash

# Clone the repo

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

cd deepseek-mcp-server



# Install dependencies

npm install



# Build in watch mode

npm run watch



# Run tests

npm test



# Lint

npm run lint

```



## Changelog



See [CHANGELOG.md](CHANGELOG.md) for version history and updates.



## License



MIT License - see [LICENSE](LICENSE) file for details



## Support



- [Documentation](https://github.com/arikusi/deepseek-mcp-server#readme)

- [Bug Reports](https://github.com/arikusi/deepseek-mcp-server/issues)

- [Discussions](https://github.com/arikusi/deepseek-mcp-server/discussions)

- Contact: [GitHub Issues](https://github.com/arikusi/deepseek-mcp-server/issues)



## Resources



- [DeepSeek Platform](https://platform.deepseek.com) - Get your API key

- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification

- [DeepSeek API Documentation](https://api-docs.deepseek.com) - API reference



## Acknowledgments



- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)

- Uses [OpenAI SDK](https://github.com/openai/openai-node) for API compatibility

- Created for the MCP community



---



**Made by [@arikusi](https://github.com/arikusi)**



This is an unofficial community project and is not affiliated with DeepSeek.