DeepL Simple Python

We made this very simple version of the DeepL MCP Server to show how this can be done, in a real-world use case. Like, although this is stripped down, you can totally use it in production.

Prerequisites

• You don't need to use uv to install and manage your dependencies, but here we do.
• You'll also need a DeepL API key, which you can get here.

Setup using uv

Installing uv

If you don't have uv installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

1. Get to the right folder

cd workshops/deepl-simple-python

2. Create your virtual environment

# Create a new virtual environment
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

3. Install dependencies

# Install all required packages
uv sync

Or install packages individually:

uv add fastmcp
uv add deepl
uv add fastmcp

4. Set Up environment variables

Create a .env file or set your DeepL API key:

# Option 1: Export environment variable
export DEEPL_API_KEY="your-deepl-api-key-here"

# Option 2: Create .env file
echo "DEEPL_API_KEY=your-deepl-api-key-here" > .env

Usage

Installing in your favorite desktop AI client

You'll probably want to install this server in your favorite local AI client, like Claude Desktop, ChatGPT for Desktop, Cursor, Windsurf, etc. To do so, you'll want to insert something like this into the client's configuration JSON:

"deepl-simple-python": {
   "command": "/Users/sofo/.local/bin/uv",
   "args": [
      "--directory",
      "/Users/sofo/Code/deepl-mcp-server/workshops/deepl-simple-python",
      "run",
      "fastmcp",
      "run",
      "deepl-simple.py"
   ],
   "env": {
      "DEEPL_API_KEY": "eaa91948-f5af-4e32-ad8f-8de58ae51b73"
   }
}

The tools

The tools progress from very simple to a slightly elaborate:

• translate-dude(): takes no arguments, and returns the same text every time. No API calls. Simplicity itself!
• get-source-languages(): retrieves the list of source languages supported by DeepL.
• get-target-languages(): retrieves the list of target languages supported by DeepL.
• translate-text(): translates text into a target language using the DeepL API. This one accepts the text to translate, the target language code, and an optional formality value.

Troubleshooting

Common Issues

1. Missing API Key

   Error: DEEPL_API_KEY environment variable not set
   

   Solution: Set your DeepL API key as described in step 4 above.

2. Python Version Error

   Error: Python >=3.10 required
   

   Solution: Install Python 3.13 or use uv python install 3.13.

3. Import Errors

   ModuleNotFoundError: No module named 'fastmcp'
   

   Solution: Ensure virtual environment is activated and run uv sync.

Getting Help

• Review DeepL API documentation
• Check the FastMCP documentation

License

This project follows the same license as the parent repository.