DeepL MCP Server

A Model Context Protocol (MCP) server that provides translation capabilities using the DeepL API using python and fastmcp.

Working Demo

Features

Translate text between numerous languages
Rephrase text using DeepL's capabilities
Access to all DeepL API languages and features
Automatic language detection
Formality control for supported languages
Batch translation and document translation
Usage and quota reporting
Translation history and usage analysis
Support for multiple MCP transports: stdio, SSE, and Streamable HTTP

Installation

Standard (Local) Installation

Clone the repository:

git clone https://github.com/AlwaysSany/deepl-fastmcp-python-server.git
cd deepl-fastmcp-python-server

Install uv (recommended) or use pip:

With pip,
```
pip install uv 
```
With pipx,
```
pipx install uv
```
Install dependencies:
```
uv sync
```
Set your environment variables:

Create a .env file or export DEEPL_AUTH_KEY in your shell.You can do this by running the following command and then update the .env file with your DeepL API key:
```
cp .env.example .env
```
Example .env file,
```
DEEPL_AUTH_KEY=your_deepl_api_key
```

Run the server:

Normal mode:

uv run python main.py --transport stdio

To run with Streamable HTTP transport (recommended for web deployments):

uv run python main.py --transport streamable-http --host 127.0.0.1 --port 8000

To run with SSE transport:

uv run python main.py --transport sse --host 127.0.0.1 --port 8000

Development mode:

uv run mcp dev main.py

It will show some messages in the terminal like this:

Spawned stdio transport Connected MCP client to backing server transport

Created web app transport

Set up MCP proxy

🔍 MCP Inspector is up and running at http://127.0.0.1:6274

MCP Inspector,

MCP Inspector

Dockerized Installation

Build the Docker image:
```
docker build -t deepl-fastmcp-server .
```

Run the container:

docker run -e DEEPL_AUTH_KEY=your_deepl_api_key -p 8000:8000 deepl-fastmcp-server

Docker Compose

Create a .env file in the project root:
```
DEEPL_AUTH_KEY=your_deepl_api_key
```
Start the service:
```
docker compose up --build
```
This will build the image and start the server, mapping port 8000 on your host to the container.

Configuration

DeepL API Key

You'll need a DeepL API key to use this server. You can get one by signing up at DeepL API. With a DeepL API Free account you can translate up to 500,000 characters/month for free.

Required environment variables:

DEEPL_AUTH_KEY (required): Your DeepL API key.
DEEPL_SERVER_URL (optional): Override the DeepL API endpoint (default: https://api-free.deepl.com).

MCP Transports

This server supports the following MCP transports:

Stdio: Default transport for local usage.
SSE (Server-Sent Events): Ideal for real-time event-based communication.
Streamable HTTP: Suitable for HTTP-based streaming applications.

To configure these transports, ensure your environment supports the required protocols and dependencies.

Usage

Use with Cursor IDE,

Click on File > Preferences > Cursor Settings > MCP > MCP Servers > Add new global MCP server

and paste the following json:

{
  "mcpServers": {
    "deepl-fastmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/yourdeepl-fastmcp-python-server/.venv",
        "run",
        "--with",
        "mcp",
        "python",
        "/path/to/your/deepl-fastmcp-python-server/main.py",
        "--transport",
        "streamable-http",
        "--host",
        "127.0.0.1",
        "--port",
        "8000"
      ]
    }
  }
}

Note: To use Streamable HTTP or SSE transports with Cursor IDE, change the "--transport", "stdio" line to "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" or "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectively, and adjust the host and port as needed.

For example,

  "mcpServers": {
    "deepl-fastmcp": {
        "type": "sse",
        "url": "http://127.0.0.1:8000/sse"
    }
  }

and then run mcp server from terminal uv run main.py --transport sse --host 127.0.0.1 --port 8000

Cursor Settings,

Cursor MCP Server

Use with Claude Desktop

This MCP server integrates with Claude Desktop to provide translation capabilities directly in your conversations with Claude.

Configuration Steps

Install Claude Desktop if you haven't already
Create or edit the Claude Desktop configuration file:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %AppData%\Claude\claude_desktop_config.json
- On Linux: ~/.config/Claude/claude_desktop_config.json
Add the DeepL MCP server configuration:

{
  "mcpServers": {
    "deepl-fastmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/yourdeepl-fastmcp-python-server/.venv",
        "run",
        "--with",
        "mcp",
        "python",
        "/path/to/your/deepl-fastmcp-python-server/main.py",
        "--transport",
        "streamable-http",
        "--host",
        "127.0.0.1",
        "--port",
        "8000"
      ]
    }
  }
}

Note: To use Streamable HTTP or SSE transports with Claude Desktop, change the "--transport", "stdio" line to "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" or "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectively, and adjust the host and port as needed.

Available Tools

This server provides the following tools:

translate_text: Translate text to a target language
rephrase_text: Rephrase text in the same or different language
batch_translate: Translate multiple texts in a single request
translate_document: Translate a document file using DeepL API
detect_language: Detect the language of given text
get_translation_history: Get recent translation operation history
analyze_usage_patterns: Analyze translation usage patterns from history

Available Resources

The following resources are available for read-only data access (can be loaded into LLM context):

usage://deepl: DeepL API usage info.
deepl://languages/source: Supported source languages.
deepl://languages/target: Supported target languages.
deepl://glossaries: Supported glossary language pairs.
history://translations: Recent translation operation history (same as get_translation_history tool)
usage://patterns: Usage pattern analysis (same as analyze_usage_patterns tool)

Available Prompts

The following prompt is available for LLMs:

summarize: Returns a message instructing the LLM to summarize a given text.

Example usage:

@mcp.prompt("summarize")
def summarize_prompt(text: str) -> str:
    return f"Please summarize the following text:\n\n{text}"

Tool Details

<details> <summary>🖼️ Click to see the tool details</summary>

translate_text

Translate text between languages using the DeepL API.

Parameters:
- text: The text to translate
- target_language: Target language code (e.g., 'EN', 'DE', 'FR', 'ES', 'IT', 'JA', 'ZH')
- source_language (optional): Source language code
- formality (optional): Controls formality level ('less', 'more', 'default', 'prefer_less', 'prefer_more')
- preserve_formatting (optional): Whether to preserve formatting
- split_sentences (optional): How to split sentences
- tag_handling (optional): How to handle tags

rephrase_text

Rephrase text in the same or different language using the DeepL API.

Parameters:
- text: The text to rephrase
- target_language: Language code for rephrasing
- formality (optional): Desired formality level
- context (optional): Additional context for better rephrasing

batch_translate

Translate multiple texts in a single request.

Parameters:
- texts: List of texts to translate
- target_language: Target language code
- source_language (optional): Source language code
- formality (optional): Formality level
- preserve_formatting (optional): Whether to preserve formatting

translate_document

Translate a document file using DeepL API.

Parameters:
- file_path: Path to the document file
- target_language: Target language code
- output_path (optional): Output path for translated document
- formality (optional): Formality level
- `preserve_forma

Deepl Fastmcp Python Server

Install / Use

README