DeepL

Traduce texto usando la API de DeepL.

Documentación

Servidor MCP de DeepL

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de traducción utilizando la API de DeepL usando Python y fastmcp.

Demostración en funcionamiento

Características

Traducir texto entre numerosos idiomas
Reformular texto usando las capacidades de DeepL
Acceso a todos los idiomas y funciones de la API de DeepL
Detección automática de idioma
Control de formalidad para idiomas compatibles
Traducción por lotes y traducción de documentos
Informes de uso y cuota
Historial de traducciones y análisis de uso
Soporte para múltiples transportes MCP: stdio, SSE y HTTP transmisible

Instalación

Instalación estándar (local)

Clonar el repositorio:

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

Instalar uv (recomendado) o usar pip:

Con pip,
```
pip install uv 
```
Con pipx,
```
pipx install uv
```
Instalar dependencias:
```
uv sync
```
Configurar las variables de entorno:

Crea un archivo .env o exporta DEEPL_AUTH_KEY en tu shell. Puedes hacerlo ejecutando el siguiente comando y luego actualizando el archivo .env con tu clave de API de DeepL:
```
cp .env.example .env
```
Ejemplo de archivo .env,
```
DEEPL_AUTH_KEY=your_deepl_api_key
```

Ejecutar el servidor:

Modo Normal:

uv run python main.py --transport stdio

Para ejecutar con transporte HTTP transmisible (recomendado para despliegues web):

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

Para ejecutar con transporte SSE:

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

Modo Desarrollo:

uv run mcp dev main.py

Mostrará algunos mensajes en la terminal como este:

Transporte stdio generado. Cliente MCP conectado al servidor de transporte de respaldo.

Aplicación web de transporte creada.

Proxy MCP configurado.

🔍 MCP Inspector está en funcionamiento en http://127.0.0.1:6274

MCP Inspector,

MCP Inspector

Instalación con Docker

Construir la imagen de Docker:
```
docker build -t deepl-fastmcp-server .
```

Ejecutar el contenedor:

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

Docker Compose

Crear un archivo .env en la raíz del proyecto:
```
DEEPL_AUTH_KEY=your_deepl_api_key
```
Iniciar el servicio:
```
docker compose up --build
```
Esto construirá la imagen e iniciará el servidor, mapeando el puerto 8000 de tu host al contenedor.

Configuración

Clave de API de DeepL

Necesitarás una clave de API de DeepL para usar este servidor. Puedes obtener una registrándote en DeepL API. Con una cuenta gratuita de DeepL API puedes traducir hasta 500,000 caracteres al mes de forma gratuita.

Variables de entorno requeridas:

DEEPL_AUTH_KEY (obligatorio): Tu clave de API de DeepL.
DEEPL_SERVER_URL (opcional): Sobrescribir el endpoint de la API de DeepL (predeterminado: https://api-free.deepl.com).

Transportes MCP

Este servidor soporta los siguientes transportes MCP:

Stdio: Transporte predeterminado para uso local.
SSE (Server-Sent Events): Ideal para comunicación en tiempo real basada en eventos.
HTTP transmisible: Adecuado para aplicaciones de streaming basadas en HTTP.

Para configurar estos transportes, asegúrate de que tu entorno soporte los protocolos y dependencias requeridos.

Uso

Uso con Cursor IDE,

Haz clic en File > Preferences > Cursor Settings > MCP > MCP Servers > Add new global MCP server

y pega el siguiente 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"
      ]
    }
  }
}

Nota: Para usar transportes HTTP transmisible o SSE con Cursor IDE, cambia la línea "--transport", "stdio" a "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" o "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectivamente, y ajusta el host y el puerto según sea necesario.

Por ejemplo,

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

y luego ejecuta el servidor mcp desde la terminal uv run main.py --transport sse --host 127.0.0.1 --port 8000

Configuración de Cursor,

Cursor MCP Server

Uso con Claude Desktop

Este servidor MCP se integra con Claude Desktop para proporcionar capacidades de traducción directamente en tus conversaciones con Claude.

Pasos de configuración

Instala Claude Desktop si aún no lo has hecho
Crea o edita el archivo de configuración de Claude Desktop:
- En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows: %AppData%\Claude\claude_desktop_config.json
- En Linux: ~/.config/Claude/claude_desktop_config.json
Agrega la configuración del servidor MCP de DeepL:

{
  "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"
      ]
    }
  }
}

Nota: Para usar transportes HTTP transmisible o SSE con Claude Desktop, cambia la línea "--transport", "stdio" a "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" o "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectivamente, y ajusta el host y el puerto según sea necesario.

Herramientas disponibles

Este servidor proporciona las siguientes herramientas:

translate_text: Traducir texto a un idioma de destino
rephrase_text: Reformular texto en el mismo o diferente idioma
batch_translate: Traducir múltiples textos en una sola solicitud
translate_document: Traducir un archivo de documento usando la API de DeepL
detect_language: Detectar el idioma de un texto dado
get_translation_history: Obtener el historial reciente de operaciones de traducción
analyze_usage_patterns: Analizar patrones de uso de traducción del historial

Recursos disponibles

Los siguientes recursos están disponibles para acceso de datos de solo lectura (se pueden cargar en el contexto del LLM):

usage://deepl: Información de uso de la API de DeepL.
deepl://languages/source: Idiomas de origen compatibles.
deepl://languages/target: Idiomas de destino compatibles.
deepl://glossaries: Pares de idiomas de glosario compatibles.
history://translations: Historial reciente de operaciones de traducción (igual que la herramienta get_translation_history)
usage://patterns: Análisis de patrones de uso (igual que la herramienta analyze_usage_patterns)

Prompts disponibles

El siguiente prompt está disponible para LLMs:

summarize: Devuelve un mensaje que instruye al LLM a resumir un texto dado.

Ejemplo de uso:

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

Detalles de las herramientas

🖼️ Haz clic para ver los detalles de la herramienta

translate_text

Traducir texto entre idiomas usando la API de DeepL.

Parámetros:
- text: El texto a traducir
- target_language: Código del idioma de destino (ej., 'EN', 'DE', 'FR', 'ES', 'IT', 'JA', 'ZH')
- source_language (opcional): Código del idioma de origen
- formality (opcional): Controla el nivel de formalidad ('less', 'more', 'default', 'prefer_less', 'prefer_more')
- preserve_formatting (opcional): Si se debe preservar el formato
- split_sentences (opcional): Cómo dividir oraciones
- tag_handling (opcional): Cómo manejar etiquetas

rephrase_text

Reformular texto en el mismo o diferente idioma usando la API de DeepL.

Parámetros:
- text: El texto a reformular
- target_language: Código de idioma para reformular
- formality (opcional): Nivel de formalidad deseado
- context (opcional): Contexto adicional para una mejor reformulación

batch_translate

Traducir múltiples textos en una sola solicitud.

Parámetros:
- texts: Lista de textos a traducir
- target_language: Código del idioma de destino
- source_language (opcional): Código del idioma de origen
- formality (opcional): Nivel de formalidad
- preserve_formatting (opcional): Si se debe preservar el formato

translate_document

Traducir un archivo de documento usando la API de DeepL.

Parámetros:
- file_path: Ruta al archivo de documento
- target_language: Código del idioma de destino
- output_path (opcional): Ruta de salida para el documento traducido
- formality (opcional): Nivel de formalidad
- preserve_formatting (opcional): Si se debe preservar el formato del documento

detect_language

Detectar el idioma de un texto dado usando DeepL.

Parámetros:
- text: Texto a analizar para detección de idioma

get_translation_history

No se requieren parámetros. Consulta la salida de la herramienta para más detalles.

analyze_usage_patterns

No se requieren parámetros. Consulta la salida de la herramienta para más detalles.

Idiomas compatibles

La API de DeepL soporta una amplia variedad de idiomas para traducción. Puedes usar las herramientas get_source_languages y get_target_languages, o los recursos deepl://languages/source y deepl://languages/target, para ver todos los idiomas actualmente compatibles.

Algunos ejemplos de idiomas compatibles incluyen:

Inglés (en, en-US, en-GB)
Alemán (de)
Español (es)
Francés (fr)
Italiano (it)
Japonés (ja)
Chino (zh)
Portugués (pt-BR, pt-PT)
Ruso (ru)
Y muchos más

Depuración

Para información de depuración, visita la documentación de depuración de MCP.

Manejo de errores

Si encuentras errores con la API de DeepL, verifica lo siguiente:

Verifica que tu clave de API sea correcta
Asegúrate de no exceder los límites de uso de tu API
Confirma que los códigos de idioma que usas sean compatibles

Desplegar en servidor

Para desplegar en un servidor (render.com), necesitas compilar tu pyproject.toml a requirements.txt porque no soporta uv en este momento. Para hacerlo, puedes usar los siguientes comandos:

uv pip compile pyproject.toml > requirements.txt

luego, crea un archivo runtime.txt con la versión de Python,

echo "python-3.13.3" > runtime.txt

finalmente, configura las variables de entorno PORT, DEEPL_SERVER_URL y DEEPL_AUTH_KEY con tu clave de API de DeepL en el espacio de trabajo de render.com antes de configurar el punto de entrada,

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

Despliegue

El servidor MCP está activo y accesible en Render.com.

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

Puedes interactuar con la API en la URL anterior.

Licencia

MIT

Tareas pendientes

Agregar más casos de prueba
Agregar más características
Agregar más documentación
Agregar más características de seguridad
Agregar más registro de eventos
Agregar más monitoreo
Agregar más optimización de rendimiento

Contribuciones

¡Las contribuciones son bienvenidas! Si tienes sugerencias para mejoras o nuevas características, por favor abre un issue o envía una solicitud de extracción.

Consulta más en Contribuciones

Contacto

Autor: Sany Ahmed
Correo electrónico: sany2k8@gmail.com