DeepL Model Context Protocol (MCP) Server

1.1.0 · active · verified Sun Apr 19

The deepl-mcp-server package provides a Model Context Protocol (MCP) server that integrates DeepL's translation capabilities. It allows other applications, notably Claude Desktop, to leverage DeepL's API for features like text and document translation, rephrasing, automatic language detection, formality control, and glossary support. The current stable version is 1.1.0. This package is primarily designed as a standalone server or CLI tool, rather than a library for programmatic import. Its key differentiator is simplifying DeepL API access for MCP-compatible clients, particularly its direct configuration support for Claude Desktop, enabling AI assistants to perform high-quality translations. Release cadence is infrequent, focusing on stability and integration enhancements. It abstracts the complexities of the DeepL API, offering a streamlined interface via the MCP specification.

Common errors

```
DEEPL_API_KEY is not defined. Please set it as an environment variable.
```
cause The DeepL API key was not provided when starting the server.

fix Set the `DEEPL_API_KEY` environment variable, e.g., `DEEPL_API_KEY="YOUR_KEY" npx deepl-mcp-server`.
```
command not found: deepl-mcp-server
```
cause The `deepl-mcp-server` command is not available in the current shell's PATH, or `npx` is not installed/configured.

fix Ensure `npx` is installed and updated (`npm install -g npm@latest`) or install the package globally (`npm install -g deepl-mcp-server`). Alternatively, provide the full path to the executable if running locally.
```
Failed to load MCP server config for 'deepl'
```
cause Claude Desktop encountered an issue reading or executing the command defined for the 'deepl' MCP server in `claude_desktop_config.json`.

fix Verify the `command` and `args` paths in your `claude_desktop_config.json` are correct and absolute, and that the specified `DEEPL_API_KEY` is valid. Check Claude Desktop logs for more specifics.

Warnings

gotcha A DeepL API key is absolutely essential for the server to function. Without it, translation requests will fail. Sign up at DeepL API to obtain one.
Fix: Set the `DEEPL_API_KEY` environment variable before running the server (e.g., `DEEPL_API_KEY="your_key" npx deepl-mcp-server`).
gotcha This package is designed as a standalone server and command-line tool, not a library for direct programmatic import into other JavaScript or TypeScript applications. Attempting to `import` or `require` it as a module for in-process use will likely fail or lead to unsupported behavior.
Fix: Run the server as a separate process using `npx deepl-mcp-server` or `node /path/to/src/index.mjs`. Interact with it via HTTP requests from your application.
gotcha When installing locally and configuring for Claude Desktop, ensure you provide an *absolute path* to the `index.mjs` file or the installed package directory. Relative paths will cause Claude Desktop to fail finding and launching the server.
Fix: Use a full path like `/Users/youruser/Code/deepl-mcp-server/src/index.mjs` in your Claude Desktop configuration (`claude_desktop_config.json`).
gotcha The server's exact port is not explicitly stated as configurable in the provided README. It's common for Node.js servers to default to `3000` or `8080`, but this might vary or be configurable through unmentioned environment variables. Check server startup logs for the exact port.
Fix: Inspect the console output when the server starts to confirm the active port, and adjust any client requests (e.g., `curl`) accordingly.

Install

npm install deepl-mcp-server npm
yarn add deepl-mcp-server yarn
pnpm add deepl-mcp-server pnpm

Imports

deepl-mcp-server
wrong:
```
import { translate } from 'deepl-mcp-server'
```
correct:
```
npx deepl-mcp-server
```
This package is primarily a command-line interface (CLI) and server process. It is meant to be executed, not imported as a library into other JavaScript applications.
DEEPL_API_KEY
wrong:
```
import { DEEPL_API_KEY } from 'deepl-mcp-server'
```
correct:
```
DEEPL_API_KEY="{YOUR_API_KEY}" npx deepl-mcp-server
```
The DeepL API Key is a mandatory environment variable for server operation. It is not an importable JavaScript symbol.
index.mjs
wrong:
```
import * as server from 'deepl-mcp-server/src/index.mjs'
```
correct:
```
node /path/to/your/deepl-mcp-server/src/index.mjs
```
For direct execution of the local source (e.g., during development), the main ESM entry point `index.mjs` can be run with `node`. Direct import of internal modules for programmatic use is generally not supported or recommended.

Quickstart

This quickstart demonstrates how to launch the DeepL MCP server via npx with an API key, then interact with it using curl to call one of its available tools, like fetching source languages.

DEEPL_API_KEY="YOUR_DEEPL_API_KEY" npx deepl-mcp-server &

# Wait a moment for the server to start (it typically runs on port 3000 by default, though not explicitly stated)
# Assuming it runs on default port 3000, as is common for Node.js servers

# Test with a simple request to get available source languages
curl -X POST -H "Content-Type: application/json" \
  -d '{ "tool_code": "get-source-languages", "tool_name": "get-source-languages" }' \
  http://localhost:3000/v1/tools/call

# Example to translate text
# This call structure is based on the MCP specification, which might require a more complex payload
# The actual body for translate-text would involve 'text', 'target_lang', 'source_lang'
# For this quickstart, we'll demonstrate a conceptual call.

# Note: Replace 'YOUR_DEEPL_API_KEY' with an actual key to run successfully.
# The server logs its port on startup; adjust http://localhost:3000 if different.

view raw JSON →