deepl-mcp-server

A Model Context Protocol (MCP) server that exposes DeepL text translation, document translation, rephrasing, and glossary and style rule lookups as MCP tools.

Usage

You need Node.js 18 or newer and a DeepL API key. Pick an API plan and create a key in your DeepL account.

The server communicates over stdio, so it is normally started by an MCP client rather than by hand. To try it directly:

DEEPL_API_KEY=your-api-key npx -y deepl-mcp-server

It exits immediately if DEEPL_API_KEY is not set.

To work on the server itself:

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

Configuration

Register it as a stdio server with DEEPL_API_KEY in the server's environment. In Claude Code:

claude mcp add deepl --env DEEPL_API_KEY=your-api-key -- npx -y deepl-mcp-server

For clients configured through a JSON file:

{
  "mcpServers": {
    "deepl": {
      "command": "npx",
      "args": ["-y", "deepl-mcp-server"],
      "env": {
        "DEEPL_API_KEY": "your-api-key"
      }
    }
  }
}

Where that file lives and how each client expects local stdio servers to be declared:

• Claude Code
• Claude Desktop
• Cursor
• VS Code

To run a local checkout instead of the published package, use node as the command and the absolute path to src/index.mjs as the argument.

Tools

Tool	Description	Parameters
translate-text	Translates text into a target language.	text, targetLangCode, sourceLangCode?, formality?, glossaryId?, styleId?, context?, preserveFormatting?, splitSentences?, customInstructions?
translate-document	Translates a document file (PDF, DOCX, PPTX, XLSX, HTML, TXT, and more) and writes the result to disk.	inputFile, targetLangCode, outputFile?, sourceLangCode?, formality?, glossaryId?, styleId?, outputFormat?
rephrase-text	Rephrases text, optionally into another language.	text, targetLangCode?, style?, tone?
get-source-languages	Lists the language codes accepted as a translation source.	none
get-target-languages	Lists the language codes accepted as a translation target.	none
get-writing-styles	Lists the style values rephrase-text accepts.	none
get-writing-tones	Lists the tone values rephrase-text accepts.	none
list-glossaries	Lists every glossary in the account with its id, name, dictionaries, and creation time.	none
get-glossary-info	Returns the same metadata as list-glossaries for a single glossary.	glossaryId
get-glossary-dictionary-entries	Returns the term entries of one glossary dictionary, meaning one language pair in one direction.	glossaryId, sourceLangCode, targetLangCode
list-style-rules	Lists the style rules in the account with their id, name, language, and timestamps.	page?, pageSize?, detailed?
get-style-rule	Returns one style rule in full, including its configured rules and custom instructions.	styleId
get-custom-instruction	Returns a single custom instruction belonging to a style rule.	styleId, instructionId

Notes:

• text takes either a single string or an array of strings. Each entry is translated or rephrased independently.
• Language codes are ISO 639-1, optionally with a region (en-US). Omitting sourceLangCode triggers automatic detection. A target code whose language requires a region gets a default applied: en becomes en-US, pt becomes pt-BR, zh becomes zh-Hans.
• Glossary dictionaries are keyed by non-regional codes, so get-glossary-dictionary-entries drops any region you pass.
• Translating with a glossary requires an explicit sourceLangCode.
• formality accepts less, more, default, prefer_less, and prefer_more. The prefer_* values fall back to the default when the target language has no formality support.
• translate-document reads and writes files on the machine running the server. Without outputFile, the output path is derived from the input by appending the target language code, for example report_de.pdf. With outputFormat, the derived path uses that extension instead.
• Style rules and custom instructions are read-only here. Create and edit them in your DeepL account.

License

MIT