DeepL MCP Server

# DeepL MCP Server [](https://nodejs.org) [](https://opensource.org/licenses/MIT) An MCP (Model Context Protocol) server providing high-quality translation capabilities via the [DeepL API](https://www.deepl.com/pro-api). ## Features This server provides 5 tools for working with DeepL: | Tool | Description | Required Params | |------|-------------|-----------------| | `translate_text` | Translate text with formality control, context, and glossary support | `text`, `target_lang` | | `rephrase_text` | Improve text clarity and style using DeepL Write (Pro only) | `text` | | `get_source_languages` | List all available source languages | — | | `get_target_languages` | List all target languages with formality support info | — | | `get_usage` | Get API usage statistics (character count and limits) | — | ### Translation Features - **Formality control** — Adjust tone for formal/informal contexts (supported languages: DE, FR, IT, ES, NL, PL, PT, JA, RU) - **Context parameter** — Provide additional context for better accuracy (not billed) - **Glossary support** — Use custom terminology with glossary IDs - **Batch translation** — Translate multiple texts in a single request - **Preserve formatting** — Keep original text formatting - **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](https://www.deepl.com/pro-api) (Free tier available) ## Quick Start ### 1. Clone and Build ```bash 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`): ```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): ```json { "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 ```json { "text": "Hello, how are you?", "target_lang": "DE" } ``` ### Formal Translation with Context ```json { "text": "Thanks for your help!", "target_lang": "DE", "formality": "more", "context": "Business email to a client" } ``` ### Batch Translation ```json { "text": ["Hello", "Goodbye", "Thank you"], "target_lang": "FR" } ``` ### Check API Usage Use `get_usage` to see your current quota: ```json { "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 - **429** — Rate limit exceeded - **456** — Quota exceeded ## Development ```bash # Watch mode (auto-rebuild) npm run watch # Manual build npm run build # Run the server npm start # Test with MCP Inspector npm run inspector ``` ## License MIT License — see [LICENSE](LICENSE) file. ## Links - [DeepL API Documentation](https://developers.deepl.com/docs) - [DeepL Pro API](https://www.deepl.com/pro-api) — Sign up for API access - [Model Context Protocol](https://modelcontextprotocol.io) — MCP documentation