deepl-mcp-server
Version:
MCP server for DeepL translation API
92 lines (68 loc) • 7.72 kB
Markdown
# deepl-mcp-server
[](https://www.npmjs.org/package/deepl-mcp-server)
[](https://github.com/DeepL/deepl-mcp-server/blob/main/LICENSE)
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](https://www.deepl.com/pro-api?utm_source=github&utm_medium=github-mcp-server-readme) 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:
```bash
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:
```bash
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:
```bash
claude mcp add deepl --env DEEPL_API_KEY=your-api-key -- npx -y deepl-mcp-server
```
For clients configured through a JSON file:
```json
{
"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](https://code.claude.com/docs/en/mcp)
- [Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
- [Cursor](https://cursor.com/docs/context/mcp)
- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
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