DeepL MCP 서버

DeepL API를 통해 고품질 번역 기능을 제공하는 MCP(Model Context Protocol) 서버입니다.

기능

이 서버는 DeepL 작업을 위한 24가지 도구를 제공합니다:

번역 기능

• 차세대 모델 선택 — quality_optimized 또는 prefer_quality_optimized와 같은 model_type 값 사용

• 격식 제어 — 격식/비격식 문맥에 맞게 어조 조정

• 문맥 매개변수 — 더 나은 정확도를 위해 추가 문맥 제공 (과금되지 않음)

• 용어집 지원 — DeepL v3 용어집 생성, 목록 조회, 검사, 사용 및 삭제

• 일괄 번역 — 단일 요청으로 여러 텍스트 번역

• 서식 유지 — 원본 텍스트 서식 유지

• HTML/XML 태그 처리 — tag_handling, tag_handling_version, ignore_tags, splitting_tags 및 관련 옵션 사용

• 과금 가시성 — show_billed_characters를 사용하여 번역 응답에 과금된 문자 수 포함

• 문서 번역 — 번역된 파일 업로드, 폴링 및 다운로드

• v3 언어 메타데이터 — 제품별 언어 지원 및 기능 규칙 검색

• 번역 메모리 — 계정 번역 메모리 목록 조회 및 번역 요청에 사용

• 스타일 규칙 — 스타일 규칙 목록 조회, 생성, 검사, 이름 변경, 삭제 및 사용

• 음성 세션 설정 — DeepL Voice 실시간 WebSocket 세션 요청 또는 재연결; 오디오 스트리밍은 반환된 WebSocket URL을 통해 수행됨

• DeepL Write 옵션 — 플랜이 Write API를 지원하는 경우 writing_style 및 tone으로 문장 재구성

• 문장 분리 제어 — 문장 분리 방식 제어

API 유형 자동 감지

서버는 키 형식을 기반으로 Free 또는 Pro API 사용 여부를 자동으로 감지합니다:

• :fx로 끝나는 키 → Free API (api-free.deepl.com)

• 기타 키 → Pro API (api.deepl.com)

Related MCP server: AiryLark MCP Translation Server

사전 요구 사항

• Node.js 18+ (Node.js 25 포함)

• DeepL API 키 — 여기에서 가입 (무료 티어 제공)

빠른 시작

1. 복제 및 빌드

git clone https://github.com/watchdealer-pavel/deepl-mcp-server.git
cd deepl-mcp-server
npm install

2. MCP 클라이언트 구성

MCP 클라이언트 구성에 추가:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "deepl": {
      "command": "node",
      "args": ["/path/to/deepl-mcp-server/build/index.js"],
      "env": {
        "DEEPL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (프로젝트 내 .mcp.json):

{
  "mcpServers": {
    "deepl": {
      "command": "node",
      "args": ["/path/to/deepl-mcp-server/build/index.js"],
      "env": {
        "DEEPL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. MCP 클라이언트 재시작

Claude Desktop 또는 Claude Code를 재시작하여 서버를 로드합니다.

사용 예시

기본 번역

{
  "text": "Hello, how are you?",
  "target_lang": "DE"
}

문맥을 포함한 격식 있는 번역

{
  "text": "Thanks for your help!",
  "target_lang": "DE",
  "formality": "more",
  "context": "Business email to a client"
}

일괄 번역

{
  "text": ["Hello", "Goodbye", "Thank you"],
  "target_lang": "FR"
}

API 사용량 확인

get_usage를 사용하여 현재 할당량을 확인합니다:

{
  "character_count": 12500,
  "character_limit": 500000,
  "characters_remaining": 487500,
  "percent_used": "2.50%",
  "api_type": "Free"
}

지원 언어

소스 언어 (생략 시 자동 감지)

AR, BG, CS, DA, DE, EL, EN, ES, ET, FI, FR, HU, ID, IT, JA, KO, LT, LV, NB, NL, PL, PT, RO, RU, SK, SL, SV, TR, UK, ZH

타겟 언어

모든 소스 언어 및 지역별 변형:

• EN-GB — 영국 영어

• EN-US — 미국 영어

• PT-BR — 브라질 포르투갈어

• PT-PT — 유럽 포르투갈어

• ZH-HANS — 중국어 간체

• ZH-HANT — 중국어 번체

격식 지원 표시기가 포함된 전체 목록은 get_target_languages를 사용하세요.

오류 처리

서버는 일반적인 API 오류를 처리합니다:

• 400 — 잘못된 매개변수

• 401/403 — 인증 실패 또는 현재 플랜에서 사용할 수 없는 기능

• 429 — 속도 제한 초과

• 456 — 할당량 초과

보안 및 OSV 상태

이 저장소는 Google의 OSV-Scanner로 스캔되었으며 깨끗한 상태로 수정되었습니다.

• 최신 스캔 결과: 알려진 종속성 취약점 0개

• 보고서는 .osv/osv-report.json 및 .osv/osv-summary.md에 기록됨

• 수정 사항은 .osv/remediation-notes.md에 있음

• 취약한 직접 종속성 체인은 @modelcontextprotocol/sdk 및 axios 업그레이드를 통해 수정됨

로컬에서 스캔 실행:

export PATH="$HOME/.local/bin:$PATH"
osv-project-scan .

개발

# Watch mode (auto-rebuild)
npm run watch

# Manual build
npm run build

# Run the server
npm start

# Test with MCP Inspector
npm run inspector

# Run live end-to-end tests against DeepL API
# Requires DEEPL_API_KEY in the environment and consumes a small number of billable characters.
npm run test:live

라이브 테스트는 번역, 언어 목록 조회, v3 언어 메타데이터, 번역 메모리 목록 조회, 스타일 규칙 목록 조회/생성/검사/업데이트/삭제(가능한 경우), 음성 세션 요청(가능한 경우), 사용량, 용어집 생성/사용/삭제, 문서 업로드/상태/다운로드 및 DeepL Write를 수행합니다. Free API 키는 DeepL Write에 대해 예상된 플랜 오류를 반환할 수 있습니다.

라이선스

MIT 라이선스 — LICENSE 파일을 참조하세요.

링크

• DeepL API 문서

• DeepL Pro API — API 액세스 가입

• Model Context Protocol — MCP 문서