DeepL MCP Server

DeepL MCP Server

An MCP (Model Context Protocol) server providing high-quality translation capabilities via the DeepL API.

Features

This server provides 24 tools for working with DeepL:

Tool	Description	Required Params
translate_text	Translate text with formality, context, glossary, model, tag-handling, style, translation-memory, and custom-instruction options	text, target_lang
rephrase_text	Improve text clarity and style using DeepL Write with optional writing style and tone	text
get_source_languages	List v2 source languages	—
get_target_languages	List v2 target languages with formality support info	—
get_usage	Get API usage statistics	—
get_languages_v3	Retrieve beta v3 supported languages by product with feature metadata	—
get_language_products_v3	Retrieve beta v3 language products and feature rules	—
get_glossary_language_pairs	List language pairs supported by glossaries	—
list_glossaries	List v3 glossaries	—
get_glossary	Retrieve v3 glossary metadata	glossary_id
get_glossary_entries	Retrieve glossary dictionary entries	glossary_id
create_glossary	Create a v3 multilingual glossary	name, dictionaries
delete_glossary	Delete a v3 glossary	glossary_id
list_translation_memories	List v3 translation memories available to the account	—
list_style_rules	List v3 style rule lists	—
get_style_rule	Retrieve a v3 style rule list	style_id
create_style_rule	Create a v3 style rule list	name, language
update_style_rule	Update a v3 style rule list name	style_id, name
delete_style_rule	Delete a v3 style rule list	style_id
request_voice_session	Request a DeepL Voice realtime WebSocket session	source_media_content_type, target_languages
reconnect_voice_session	Request a replacement DeepL Voice realtime token	—
upload_document	Upload a local file for document translation	file_path, target_lang
get_document_status	Check document translation status	document_id, document_key
download_document	Download a translated document to a local path	document_id, document_key, output_path

Translation Features

• Next-gen model selection — Use model_type values such as quality_optimized or prefer_quality_optimized
• Formality control — Adjust tone for formal/informal contexts
• Context parameter — Provide additional context for better accuracy (not billed)
• Glossary support — Create, list, inspect, use, and delete DeepL v3 glossaries
• Batch translation — Translate multiple texts in a single request
• Preserve formatting — Keep original text formatting
• HTML/XML tag handling — Use tag_handling, tag_handling_version, ignore_tags, splitting_tags, and related options
• Billing visibility — Use show_billed_characters to include billed character counts in translation responses
• Document translation — Upload, poll, and download translated files
• v3 language metadata — Retrieve product-specific language support and feature rules
• Translation memories — List account translation memories and use them in translation requests
• Style rules — List, create, inspect, rename, delete, and use style rule lists
• Voice session setup — Request or reconnect DeepL Voice realtime WebSocket sessions; audio streaming is done by the returned WebSocket URL
• DeepL Write options — Rephrase with writing_style and tone when the plan supports Write API
• Sentence splitting control — Control how sentences are split

API Type Auto-Detection

The server automatically detects whether you're using the Free or Pro API based on your key format:

• Keys ending in :fx → Free API (api-free.deepl.com)
• Other keys → Pro API (api.deepl.com)

Prerequisites

• Node.js 18+ (including Node.js 25)
• DeepL API Key — Sign up here (Free tier available)

Quick Start

1. Clone and Build

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

2. Configure Your MCP Client

Add to your MCP client configuration:

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 in your project):

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

3. Restart Your MCP Client

Restart Claude Desktop or Claude Code to load the server.

Usage Examples

Basic Translation

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

Formal Translation with Context

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

Batch Translation

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

Check API Usage

Use get_usage to see your current quota:

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

Supported Languages

Source Languages (auto-detected if omitted)

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

Target Languages

All source languages plus regional variants:

• EN-GB — British English
• EN-US — American English
• PT-BR — Brazilian Portuguese
• PT-PT — European Portuguese
• ZH-HANS — Simplified Chinese
• ZH-HANT — Traditional Chinese

Use get_target_languages for a complete list with formality support indicators.

Error Handling

The server handles common API errors:

• 400 — Invalid parameters
• 401/403 — Authentication failed or feature not available on the current plan
• 429 — Rate limit exceeded
• 456 — Quota exceeded

Security and OSV Status

This repository has been scanned with Google's OSV-Scanner and remediated to a clean state.

• Latest scan result: 0 known dependency vulnerabilities
• Reports are written to .osv/osv-report.json and .osv/osv-summary.md
• Remediation notes are in .osv/remediation-notes.md
• The vulnerable direct dependency chains were fixed by upgrading @modelcontextprotocol/sdk and axios

Run the scan locally:

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

Development

# 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

The live test exercises translation, language listing, v3 language metadata, translation-memory listing, style-rule listing/create/get/update/delete when available, voice session request when available, usage, glossary create/use/delete, document upload/status/download, and DeepL Write. Free API keys may return an expected plan error for DeepL Write.

License

MIT License — see LICENSE file.

Links

• DeepL API Documentation
• DeepL Pro API — Sign up for API access
• Model Context Protocol — MCP documentation