deepl-fastmcp-python

This DeepL MCP server provides translation capabilities via the DeepL API using Python and the Fast MCP framework. It exposes a set of tools that allow you to translate text, rephrase content, translate multiple items in batch, translate documents, detect languages, and inspect translation usage history and patterns. The server supports multiple MCP transports, including Streamable HTTP, Server-Sent Events (SSE), and Stdio for local usage, enabling integration with tools like Cursor IDE or Claude Desktop. To use it, start the MCP server via UV as shown in the installation instructions, then connect your MCP client to the running endpoint and invoke the available tools through the MCP protocol.

Prerequisites:

• Python (recommended 3.8+)
• uv (the MCP runtime) installed in a virtual environment
• DeepL API key

Installation steps:

1. Clone the repository: git clone https://github.com/AlwaysSany/deepl-fastmcp-python-server.git cd deepl-fastmcp-python-server

2. Set up a Python virtual environment and install uv (or use your preferred method): python -m venv .venv source .venv/bin/activate # on Unix/macOS .venv\Scripts\activate # on Windows

3. Install uv (recommended) or install via pip: pip install uv

4. Install dependencies (if any are defined in requirements.txt or setup files): uv sync

5. Configure environment variables:

   • Create a .env file or export DEEPL_AUTH_KEY with your DeepL API key.
   • Example: cp .env.example .env echo "DEEPL_AUTH_KEY=your_deepl_api_key" >> .env echo "DEEPL_SERVER_URL=https://api-free.deepl.com" >> .env

6. Run the server (choose a transport):

   • Streamable HTTP (recommended for web deployments): uv run python main.py --transport streamable-http --host 127.0.0.1 --port 8000

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

   • Stdio (default for local usage): uv run python main.py --transport stdio

7. (Optional) Dockerized or Docker Compose options are provided in the README for containerized setups.

Notes:

• Ensure DEEPL_AUTH_KEY is valid and has access to the required DeepL features.
• If using Docker, you may set DEEPL_AUTH_KEY as an environment variable in the container.

Tips and common issues:

• Make sure the DeepL API key is kept secure and not committed to version control.
• If you switch transports, ensure the host/port are reachable from the client tooling (e.g., Cursor IDE or Claude Desktop).
• For Streamable HTTP, you may need to configure hosting and firewall settings to allow inbound connections.
• The MCP inspector and usage endpoints (as described in the README) can help diagnose transport and connection issues.
• If you encounter environment variable issues, verify that the .env file is correctly loaded by uv and that the DEEPL_AUTH_KEY variable is accessible to the Python process.