DeepSeek V4를 위한 MCP 서버 (v4-flash 및 v4-pro, 1M 컨텍스트)

멀티 턴 세션 (multi-turn sessions), 함수 호출 (function calling), 사고 모드 (thinking mode) 및 비용 추적 (cost tracking) 기능을 갖춘 DeepSeek V4 (v4-flash 및 v4-pro, 1M 컨텍스트)용 MCP 서버입니다.

Claude Code, Gemini CLI, Cursor, Windsurf 및 모든 MCP 호환 클라이언트와 호환됩니다.

MCP Registry, Smithery, Glama, LobeHub 및 Fronteir AI에 공식적으로 등록되었습니다.

v2.0.0은 DeepSeek V4에서 실행됩니다. 두 가지 모델인 deepseek-v4-flash (빠르고 경제적)와 deepseek-v4-pro (최고 성능)가 있으며, 두 모델 모두 1M 토큰 컨텍스트 창과 선택 가능한 사고 사슬 (chain-of-thought) 사고 모드를 제공합니다. 기존의 deepseek-chat 및 deepseek-reasoner 설정은 별칭 (alias)으로 계속 작동하므로, 드롭인 (drop-in) 업그레이드가 가능합니다.

호스팅된 엔드포인트를 직접 사용하세요 — npm install이나 Node.js가 필요하지 않습니다. 본인의 DeepSeek API 키를 준비하세요:

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": {
...

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
: 모든 프로젝트에서 사용 가능 (권장)
-s local
: 현재 프로젝트에서만 사용 가능 (기본값)
-s project
: 프로젝트 전용 .mcp.json 파일

API 키 받기: https://platform.deepseek.com

DeepSeek V4: deepseek-v4-flash 및 deepseek-v4-pro 모두 1M 컨텍스트와 선택 가능한 사고 사슬 (chain-of-thought) 사고 모드 제공
멀티 턴 세션 (Multi-Turn Sessions): session_id 파라미터를 통해 요청 간 대화 컨텍스트 유지
모델 폴백 (Model Fallback) 및 서킷 브레이커 (Circuit Breaker): 연쇄 장애를 방지하는 서킷 브레이커 보호 기능과 함께 모델 간 자동 폴백 지원
MCP 리소스 (MCP Resources): deepseek://models, deepseek://config, deepseek://usage

— 모델 정보, 설정 및 사용 통계 쿼리

사고 모드 (Thinking Mode): thinking: {type: "enabled"}를 사용하여 deepseek-chat에서 사고 기능을 활성화합니다.

JSON 출력 모드 (JSON Output Mode): json_mode: true를 통한 구조화된 JSON 응답

함수 호출 (Function Calling): 최대 128개의 도구 정의를 지원하는 OpenAI 호환 도구 사용

캐시 인식 비용 추적 (Cache-Aware Cost Tracking): 캐시 히트/미스(hit/miss) 내역을 포함한 자동 비용 계산

세션 관리 도구 (Session Management Tool): deepseek_sessions 도구를 통해 세션 목록 조회, 삭제 및 초기화

설정 가능 (Configurable): 검증 기능이 포함된 환경 기반 설정

12가지 프롬프트 템플릿 (12 Prompt Templates): 디버깅, 코드 리뷰, 함수 호출 등을 위한 템플릿

스트리밍 지원 (Streaming Support): 실시간 응답 생성

멀티모달 준비 완료 (Multimodal Ready): 텍스트 + 이미지 입력을 위한 콘텐츠 파트 타입 지원 (ENABLE_MULTIMODAL=true로 활성화)

원격 엔드포인트 (Remote Endpoint): deepseek-mcp.tahirl.com/mcp에 호스팅됨

— BYOK (Bring Your Own Key) 방식, 설치 불필요

HTTP 전송 (HTTP Transport): TRANSPORT=http를 통한 Streamable HTTP 기반의 자체 호스팅 원격 접속

Docker 준비 완료 (Docker Ready): 컨테이너화된 배포를 위한 상태 확인(health checks) 기능이 포함된 멀티 스테이지 Dockerfile

테스트 완료 (Tested): 280개의 테스트, 약 89%의 라인 커버리지(line coverage)

타입 안전성 (Type-Safe): 전체 TypeScript 구현

MCP 호환 (MCP Compatible): 모든 MCP 호환 CLI (Claude Code, Gemini CLI 등)와 작동

• Node.js 20 이상
• DeepSeek API 키 (https://platform.deepseek.com 에서 발급)

수동 설치를 선호하는 경우:

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

저장소 복제 (Clone the repository)

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

의존성 설치 (Install dependencies)

npm install

프로젝트 빌드 (Build the project)

npm run build

설정이 완료되면, 귀하의 MCP 클라이언트는 deepseek_chat 및 deepseek_sessions 도구와 3개의 MCP 리소스에 접근할 수 있습니다.

프롬프트 예시 (Example prompts):

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

귀하의 MCP 클라이언트는 자동으로 deepseek_chat 도구를 호출할 것입니다.

만약 귀하의 MCP 클라이언트가 add를 지원하지 않는다면

명령어를 사용하십시오. 설정 파일(config file)에 수동으로 추가하세요:

{
"mcpServers": {
"deepseek": {
...

설정 파일 위치 (Config file locations):

Claude Code:~/.claude.json

(projects["your-project-path"].mcpServers 섹션에 추가)

기타 MCP 클라이언트 (Other MCP clients): 클라이언트의 문서를 확인하여 설정 파일 위치를 파악하세요.

자동 비용 추적(cost tracking) 및 함수 호출(function calling) 지원을 통해 DeepSeek AI 모델과 채팅하세요.

매개변수 (Parameters):

messages

(필수): 대화 메시지 배열. role: "system" | "user" | "assistant" | "tool", content: 메시지 텍스트, tool_call_id (선택 사항): tool 역할의 메시지에 필요함

model

(선택 사항): "deepseek-v4-flash" (기본값) 또는 "deepseek-v4-pro". "deepseek-chat" 및 "deepseek-reasoner"는 v4-flash(non-thinking / thinking)로 연결되는 별칭(alias)으로 허용됩니다.

temperature

(선택 사항): 0-2, 무작위성을 제어합니다 (기본값: 1.0). 사고 모드(thinking mode)가 활성화된 경우 무시됩니다.

max_tokens

(선택 사항): 생성할 최대 토큰 수 (V4 모델은 최대 384,000까지 지원)

stream

(선택 사항): 스트리밍 모드 활성화 (기본값: false)

tools

(선택 사항): 함수 호출(function calling)을 위한 도구 정의 배열 (최대 128개)

tool_choice

(선택 사항): "auto" | "none" | "required" | {type: "function", function: {name: "..."}}

thinking

(선택 사항): 사고 모드 토글. 추론을 위해 {type: "enabled"}를 사용하거나, 빠른 답변을 위해 {type: "disabled"}를 사용합니다 (non-thinking이 기본값입니다).

reasoning_effort

(선택 사항): "high" (기본값) 또는 "max". 사고 모드가 활성화된 동안에만 적용됩니다.

json_mode

(선택 사항): JSON 출력 모드 활성화 (두 모델 모두 지원)

session_id

(선택 사항): 다회차 대화(multi-turn conversations)를 위한 세션 ID. 이전 컨텍스트가 자동으로 앞에 추가됩니다.

응답 포함 내용:

• 서식이 적용된 콘텐츠 (Content with formatting)
• 함수 호출 결과 (도구가 사용된 경우)
• 요청 정보 (토큰, 모델, USD 기준 비용)
• cost_usd 및 tool_calls 필드가 포함된 구조화된 데이터

예시 (Example):

{
"messages": [
{
...

추론 예시 (Reasoning Example) (deepseek-reasoner 별칭, v4-flash + thinking으로 라우팅됨):

{
"messages": [
{
...

Thinking mode (사고 모드)는 최종 답변에 앞서 <thinking> 태그 내에 사고 과정 (Chain-of-thought)을 반환합니다.

DeepSeek V4 Pro 예시 (가장 어려운 작업):

{
"messages": [
{
...

Function Calling (함수 호출) 예시:

{
"messages": [
{
...

모델이 함수를 호출하기로 결정하면, 응답에는 함수 이름과 인자 (arguments)가 포함된 tool_calls가 포함됩니다. 그 후 일치하는 tool_call_id를 가진 tool 역할의 메시지를 사용하여 결과를 다시 보낼 수 있습니다.

Thinking Mode (사고 모드) 예시:

{
"messages": [
{
...

Thinking mode가 활성화되면 temperature와 top_p는 자동으로 무시됩니다.

JSON Output Mode (JSON 출력 모드) 예시:

{
"messages": [
{
...

JSON mode는 모델이 유효한 JSON을 출력하도록 보장합니다. 최상의 결과를 얻으려면 프롬프트에 "json"이라는 단어를 포함하세요. 모든 모델에서 지원됩니다.

Multi-Turn Session (멀티 턴 세션) 예시:

{
"messages": [
{
...

대화 문맥 (conversation context)을 유지하려면 모든 요청에 대해 동일한 session_id를 사용하세요. 메시지는 메모리에 저장되며 자동으로 앞에 추가됩니다. HTTP 전송 (HTTP transport)에서 각 연결된 MCP 세션은 자체적으로 격리된 세션 저장소를 가집니다. 즉, 한 HTTP 클라이언트에 의해 생성된 session_id는 다른 클라이언트에게 보이지 않습니다 (아래 HTTP Transport 섹션 참조).

대화 세션을 관리합니다.

매개변수 (Parameters):

action (필수): "list" | "clear" | "delete"
session_id (선택 사항): action이 "delete"인 경우 필수

예시:

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

MCP Resources (MCP 리소스)는 서버에 대한 읽기 전용 데이터를 제공합니다:

Resource URI	설명
deepseek://models	기능, 컨텍스트 제한 및 가격 정보가 포함된 사용 가능한 모델
deepseek://config	현재 서버 설정 (API 키는 마스킹 처리됨)
deepseek://usage	실시간 사용 통계 (요청, 토큰, 비용, 세션)

모델이 재시도 가능한 오류(429, 503, 타임아웃)로 인해 실패하면, 서버는 자동으로 다른 모델로 전환(fallback)합니다:

deepseek-chat 실패 → deepseek-reasoner 시도

deepseek-reasoner 실패 → deepseek-chat 시도

서킷 브레이커 (Circuit Breaker)는 연쇄적인 장애 (cascading failures)를 방지합니다:

• CIRCUIT_BREAKER_THRESHOLD만큼의 연속적인 실패 (기본값: 5)가 발생하면, 서킷이 열리고 (opens) (빠른 실패 모드) 작동합니다.
• CIRCUIT_BREAKER_RESET_TIMEOUT ms (기본값: 30000)가 지나면, 반열림 (half-open) 상태로 진입하여 프로브 (probe) 요청을 보냅니다.
• 프로브가 성공하면, 서킷이 닫히고 (closes) 정상 운영이 재개됩니다.

FALLBACK_ENABLED=false를 통해 폴백 (Fallback) 기능을 비활성화할 수 있습니다.

프롬프트 템플릿 (총 12개):

debug_with_reasoning: 단계별 분석을 통한 코드 디버깅 (debug)
code_review_deep: 종합적인 코드 리뷰 (보안, 성능, 품질)
research_synthesis: 주제 연구 및 구조화된 보고서 생성
strategic_planning: 추론을 통한 전략적 계획 수립
explain_like_im_five: 복잡한 주제를 쉬운 용어로 설명

mathematical_proof: 수학적 명제를 엄격하게 증명
argument_validation: 논리적 오류에 대한 논증 분석
creative_ideation: 타당성 분석을 포함한 창의적 아이디어 생성
cost_comparison: 작업별 LLM 비용 비교
pair_programming: 설명을 포함한 대화형 코딩

function_call_debug: 도구 정의 및 메시지를 활용한 함수 호출 (function calling) 문제 디버깅
create_function_schema: 자연어로부터 함수 호출을 위한 JSON 스키마 (JSON Schema) 생성

각 프롬프트는 상세한 추론을 제공하도록 DeepSeek Reasoner 모델에 최적화되어 있습니다.

두 V4 모델 모두 1M 토큰의 컨텍스트 창 (context window)을 가지며, 최대 384K 출력 토큰을 지원하고, 함수 호출 (function calling), JSON 모드 (JSON mode), 그리고 선택적인 사고 사슬 (chain-of-thought) 추론을 지원합니다. 여기서는 빠른 응답을 위해 기본적으로 '비사고 (non-thinking)' 모드로 설정되어 있습니다. thinking: {type: "enabled"} (또는 deepseek-reasoner 별칭)를 사용하여 추론을 활성화할 수 있습니다.

최적 용도: 일반적인 대화, 코딩, 콘텐츠 생성, 에이전트 루프 (agent loops)
속도: 빠르고 경제적임
컨텍스트 (Context): 1M 토큰
최대 출력 (Max Output): 384K 토큰
가격: 캐시 히트 (cache hit) 시 1M당 $0.0028, 캐시 미스 (cache miss) 시 1M당 $0.14, 출력 (output) 1M당 $0.28

최적 용도: 복잡한 추론 (Complex reasoning), 수학, 어려운 다단계 작업 (multi-step tasks), 최고 품질의 출력
속도: flash 모델보다 느림, 가장 높은 성능
컨텍스트 (Context): 1M 토큰
최대 출력 (Max Output): 384K 토큰
가격: 캐시 히트 (cache hit) 1M당 $0.003625, 캐시 미스 (cache miss) 1M당 $0.435, 출력 (output) 1M당 $0.87

deepseek-chat

및

deepseek-reasoner

는 여전히 허용되며 deepseek-v4-flash로 연결됩니다

(chat = 비사고형 (non-thinking), reasoner = 사고형 (thinking)), 따라서 기존 설정이 그대로 작동합니다. DeepSeek API는 2026-07-24에 이 두 이름을 폐기할 예정이며, 이 서버가 이를 대신 V4로 변환해 줍니다.

서버는 환경 변수 (environment variables)를 통해 설정됩니다. DEEPSEEK_API_KEY를 제외한 모든 설정은 선택 사항입니다.

변수 (Variable)	기본값 (Default)	설명 (Description)
DEEPSEEK_API_KEY	(필수)	DeepSeek API 키
DEEPSEEK_BASE_URL	https://api.deepseek.com	사용자 정의 API 엔드포인트 (endpoint)
DEFAULT_MODEL	deepseek-v4-flash	요청 시 사용할 기본 모델
SHOW_COST_INFO	true	응답에 비용 정보 표시
REQUEST_TIMEOUT	60000	요청 제한 시간 (밀리초)
MAX_RETRIES	2	실패한 요청에 대한 최대 재시도 횟수
SKIP_CONNECTION_TEST	false	시작 시 API 연결 테스트 건너뛰기
MAX_MESSAGE_LENGTH	100000	최대 메시지 내용 길이 (문자 수)
SESSION_TTL_MINUTES	30	세션 유효 시간 (분 단위)
MAX_SESSIONS	100	최대 동시 세션 수
FALLBACK_ENABLED	true	오류 발생 시 자동 모델 폴백 (fallback) 활성화
CIRCUIT_BREAKER_THRESHOLD	5	서킷 브레이커 (circuit breaker)가 열리기 전 연속 실패 횟수
CIRCUIT_BREAKER_RESET_TIMEOUT	30000	서킷이 반개방 (half-open) 상태가 되기 전까지의 시간 (밀리초)
MAX_SESSION_MESSAGES	200	세션당 최대 메시지 수 (슬라이딩 윈도우 (sliding window))
ENABLE_MULTIMODAL	false	멀티모달 (multimodal, 이미지) 입력 지원 활성화
TRANSPORT	stdio	전송 모드 (Transport mode): stdio 또는 http
HTTP_PORT	3000	HTTP 서버 포트 (TRANSPORT=http인 경우)
HTTP_HOST	127.0.0.1	HTTP 전송을 위한 바인드 주소 (Bind address). 기본적으로 루프백 (Loopback)으로 설정되어 새로 실행해도 외부로 노출되지 않습니다.

원격 연결을 허용하려면 0.0.0.0으로 설정하세요 (인증(auth) 또는 전면에 프록시(proxy)가 있는 경우에만 수행하십시오) |
HTTP_AUTH_TOKEN |
(설정되지 않음) |
설정 시, POST /mcp 요청에 Authorization: Bearer <token> 헤더가 필요합니다. /health 경로는 계속 개방된 상태로 유지됩니다. 포트가 localhost 이외의 곳에서 접근 가능할 때마다 설정을 강력히 권장합니다 |
HTTP_ALLOWED_HOSTS |
(설정되지 않음) |
0.0.0.0에 바인딩할 때 DNS 리바인딩 (DNS rebinding) 방지를 위해 허용된 Host 헤더의 쉼표로 구분된 목록 (예: mcp.example.com,localhost) |

사용자 정의 설정 예시:

claude mcp add -s user deepseek npx @arikusi/deepseek-mcp-server \
-e DEEPSEEK_API_KEY=your-key \
-e SHOW_COST_INFO=false \
...

deepseek-mcp-server/
├── worker/ # Cloudflare Worker (원격 BYOK 엔드포인트)
│ ├── src/index.ts # Worker 진입점 (entry point)
...