DeepL MCP Server

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

Working Demo

MCP_DEEPL_DEMO.webm

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,

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,

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

🖼️ Click to see the tool details

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_formatting (optional): Whether to preserve document formatting

detect_language

Detect the language of given text using DeepL.

Parameters:
- text: Text to analyze for language detection

get_translation_history

No parameters required. See tool output for details.

analyze_usage_patterns

No parameters required. See tool output for details.

Supported Languages

The DeepL API supports a wide variety of languages for translation. You can use the get_source_languages and get_target_languages tools, or the deepl://languages/source and deepl://languages/target resources, to see all currently supported languages.

Some examples of supported languages include:

English (en, en-US, en-GB)
German (de)
Spanish (es)
French (fr)
Italian (it)
Japanese (ja)
Chinese (zh)
Portuguese (pt-BR, pt-PT)
Russian (ru)
And many more

Debugging

For debugging information, visit the MCP debugging documentation.

Error Handling

If you encounter errors with the DeepL API, check the following:

Verify your API key is correct
Make sure you're not exceeding your API usage limits
Confirm the language codes you're using are supported

Deploy on server

To deploy on a server(render.com), you need to compile your pyproject.toml to requirements.txt because it doesn't support uv right now. So to do that, you can use the following commands:

uv pip compile pyproject.toml > requirements.txt

then, create a runtime.txt file with the python version,

echo "python-3.13.3" > runtime.txt

finally, set the environment variable PORT, DEEPL_SERVER_URL and DEEPL_AUTH_KEY with your DeepL API key on render.com workspace before you set the entry point,

python main.py --transport sse --host 0.0.0.0 --port 8000

Deployment

The MCP server is live and accessible on Render.com.

Live Endpoint:
https://deepl-fastmcp-python-server.onrender.com/sse

You can interact with the API at the above URL.

License

MIT

TODOs

Contributing

Contributions are welcome! If you have suggestions for improvements or new features, please open an issue or submit a pull request.

See more at Contributing

Contact

Author: Sany Ahmed
Email: [email protected]

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
assets		assets
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
runtime.txt		runtime.txt
uv.lock		uv.lock

License

AlwaysSany/deepl-fastmcp-python-server

Folders and files

Latest commit

History

Repository files navigation

DeepL MCP Server

Working Demo

Features

Installation

Standard (Local) Installation

Dockerized Installation

Docker Compose

Configuration

DeepL API Key

MCP Transports

Usage

Use with Cursor IDE,

Use with Claude Desktop

Configuration Steps

Available Tools

Available Resources

Available Prompts

Tool Details

translate_text

rephrase_text

batch_translate

translate_document

detect_language

get_translation_history

analyze_usage_patterns

Supported Languages

Debugging

Error Handling

Deploy on server

Deployment

License

TODOs

Contributing

Contact

Links

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages