DeepL

Traduza texto usando a API DeepL.

GitHub
4

Documentação

Servidor MCP DeepL

Um servidor Model Context Protocol (MCP) que fornece recursos de tradução usando a API DeepL com Python e fastmcp.

Demonstração Funcional

Recursos

  • Traduza texto entre diversos idiomas
  • Reformule texto usando os recursos do DeepL
  • Acesso a todos os idiomas e recursos da API DeepL
  • Detecção automática de idioma
  • Controle de formalidade para idiomas suportados
  • Tradução em lote e tradução de documentos
  • Relatórios de uso e cota
  • Histórico de tradução e análise de uso
  • Suporte a múltiplos transportes MCP: stdio, SSE e HTTP Streamable

Instalação

Instalação Padrão (Local)

  1. Clone o repositório:

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

  2. Instale o uv (recomendado) ou use pip:

    Com pip,

    pip install uv

    Com pipx,

    pipx install uv

  3. Instale as dependências:

    uv sync

  4. Defina suas variáveis de ambiente:

    Crie um arquivo .env ou exporte DEEPL_AUTH_KEY no seu shell. Você pode fazer isso executando o seguinte comando e depois atualizando o arquivo .env com sua chave da API DeepL:

    cp .env.example .env

    Exemplo de arquivo .env,

    DEEPL_AUTH_KEY=your_deepl_api_key

  5. Execute o servidor:

    Modo Normal:

    uv run python main.py --transport stdio

    Para executar com transporte HTTP Streamable (recomendado para implantações web):

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

    Para executar com transporte SSE:

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

    Modo Desenvolvimento:

    uv run mcp dev main.py

Ele exibirá algumas mensagens no terminal como esta:

Transporte stdio iniciado. Cliente MCP conectado ao servidor de transporte de apoio

Aplicativo web de transporte criado

Proxy MCP configurado

🔍 O MCP Inspector está ativo em http://127.0.0.1:6274

MCP Inspector,

MCP Inspector

Instalação com Docker

  1. Construa a imagem Docker:

    docker build -t deepl-fastmcp-server .

  2. Execute o contêiner:

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

Docker Compose

  1. Crie um arquivo .env na raiz do projeto:

    DEEPL_AUTH_KEY=your_deepl_api_key

  2. Inicie o serviço:

    docker compose up --build

    Isso criará a imagem e iniciará o servidor, mapeando a porta 8000 do seu host para o contêiner.

Configuração

Chave da API DeepL

Você precisará de uma chave da API DeepL para usar este servidor. Você pode obter uma criando uma conta em DeepL API. Com uma conta gratuita da API DeepL, você pode traduzir até 500.000 caracteres por mês gratuitamente.

Variáveis de ambiente obrigatórias:

  • DEEPL_AUTH_KEY (obrigatório): Sua chave da API DeepL.
  • DEEPL_SERVER_URL (opcional): Substitui o endpoint da API DeepL (padrão: https://api-free.deepl.com).

Transportes MCP

Este servidor suporta os seguintes transportes MCP:

  • Stdio: Transporte padrão para uso local.
  • SSE (Server-Sent Events): Ideal para comunicação em tempo real baseada em eventos.
  • HTTP Streamable: Adequado para aplicações de streaming baseadas em HTTP.

Para configurar esses transportes, certifique-se de que seu ambiente suporte os protocolos e dependências necessários.

Uso

Uso com o Cursor IDE,

Clique em File > Preferences > Cursor Settings > MCP > MCP Servers > Add new global MCP server

e cole o seguinte 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"
      ]
    }
  }
}

Observação: Para usar transportes HTTP Streamable ou SSE com o Cursor IDE, altere a linha "--transport", "stdio" para "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" ou "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectivamente, e ajuste o host e a porta conforme necessário.

Por exemplo,

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

e depois execute o servidor MCP no terminal uv run main.py --transport sse --host 127.0.0.1 --port 8000

Configurações do Cursor,

Cursor MCP Server

Uso com o Claude Desktop

Este servidor MCP integra-se ao Claude Desktop para fornecer recursos de tradução diretamente em suas conversas com o Claude.

Etapas de Configuração

  1. Instale o Claude Desktop se ainda não o fez

  2. Crie ou edite o arquivo de configuração do Claude Desktop:

    • No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • No Windows: %AppData%\Claude\claude_desktop_config.json
    • No Linux: ~/.config/Claude/claude_desktop_config.json

  3. Adicione a configuração do servidor MCP 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"
      ]
    }
  }
}

Observação: Para usar transportes HTTP Streamable ou SSE com o Claude Desktop, altere a linha "--transport", "stdio" para "--transport", "streamable-http", "--host", "127.0.0.1", "--port", "8000" ou "--transport", "sse", "--host", "127.0.0.1", "--port", "8000" respectivamente, e ajuste o host e a porta conforme necessário.

Ferramentas Disponíveis

Este servidor fornece as seguintes ferramentas:

  • translate_text: Traduz texto para um idioma de destino
  • rephrase_text: Reformula texto no mesmo idioma ou em outro
  • batch_translate: Traduz múltiplos textos em uma única solicitação
  • translate_document: Traduz um arquivo de documento usando a API DeepL
  • detect_language: Detecta o idioma de um texto fornecido
  • get_translation_history: Obtém o histórico recente de operações de tradução
  • analyze_usage_patterns: Analisa padrões de uso de tradução a partir do histórico

Recursos Disponíveis

Os seguintes recursos estão disponíveis para acesso de dados somente leitura (podem ser carregados no contexto do LLM):

  • usage://deepl: Informações de uso da API DeepL.
  • deepl://languages/source: Idiomas de origem suportados.
  • deepl://languages/target: Idiomas de destino suportados.
  • deepl://glossaries: Pares de idiomas de glossário suportados.
  • history://translations: Histórico recente de operações de tradução (igual à ferramenta get_translation_history)
  • usage://patterns: Análise de padrões de uso (igual à ferramenta analyze_usage_patterns)

Prompts Disponíveis

O seguinte prompt está disponível para LLMs:

  • summarize: Retorna uma mensagem instruindo o LLM a resumir um texto fornecido.

    Exemplo de uso:

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

Detalhes das Ferramentas

🖼️ Clique para ver os detalhes da ferramenta

translate_text

Traduz texto entre idiomas usando a API DeepL.

  • Parâmetros:
    • text: O texto a ser traduzido
    • target_language: Código do idioma de destino (ex.: 'EN', 'DE', 'FR', 'ES', 'IT', 'JA', 'ZH')
    • source_language (opcional): Código do idioma de origem
    • formality (opcional): Controla o nível de formalidade ('less', 'more', 'default', 'prefer_less', 'prefer_more')
    • preserve_formatting (opcional): Se deve preservar a formatação
    • split_sentences (opcional): Como dividir frases
    • tag_handling (opcional): Como lidar com tags

rephrase_text

Reformula texto no mesmo idioma ou em outro usando a API DeepL.

  • Parâmetros:
    • text: O texto a ser reformulado
    • target_language: Código do idioma para reformulação
    • formality (opcional): Nível de formalidade desejado
    • context (opcional): Contexto adicional para melhor reformulação

batch_translate

Traduz múltiplos textos em uma única solicitação.

  • Parâmetros:
    • texts: Lista de textos a serem traduzidos
    • target_language: Código do idioma de destino
    • source_language (opcional): Código do idioma de origem
    • formality (opcional): Nível de formalidade
    • preserve_formatting (opcional): Se deve preservar a formatação

translate_document

Traduz um arquivo de documento usando a API DeepL.

  • Parâmetros:
    • file_path: Caminho para o arquivo do documento
    • target_language: Código do idioma de destino
    • output_path (opcional): Caminho de saída para o documento traduzido
    • formality (opcional): Nível de formalidade
    • preserve_formatting (opcional): Se deve preservar a formatação do documento

detect_language

Detecta o idioma de um texto fornecido usando o DeepL.

  • Parâmetros:
    • text: Texto a ser analisado para detecção de idioma

get_translation_history

  • Nenhum parâmetro necessário. Consulte a saída da ferramenta para detalhes.

analyze_usage_patterns

  • Nenhum parâmetro necessário. Consulte a saída da ferramenta para detalhes.

Idiomas Suportados

A API DeepL suporta uma ampla variedade de idiomas para tradução. Você pode usar as ferramentas get_source_languages e get_target_languages, ou os recursos deepl://languages/source e deepl://languages/target, para ver todos os idiomas atualmente suportados.

Alguns exemplos de idiomas suportados incluem:

  • Inglês (en, en-US, en-GB)
  • Alemão (de)
  • Espanhol (es)
  • Francês (fr)
  • Italiano (it)
  • Japonês (ja)
  • Chinês (zh)
  • Português (pt-BR, pt-PT)
  • Russo (ru)
  • E muitos outros

Depuração

Para informações de depuração, visite a documentação de depuração do MCP.

Tratamento de Erros

Se você encontrar erros com a API DeepL, verifique o seguinte:

  • Confirme se sua chave de API está correta
  • Certifique-se de não estar excedendo os limites de uso da API
  • Confirme se os códigos de idioma que você está usando são suportados

Implantação no servidor

Para implantar em um servidor (render.com), você precisa compilar seu pyproject.toml para requirements.txt porque ele não suporta uv atualmente. Para fazer isso, você pode usar os seguintes comandos:

uv pip compile pyproject.toml > requirements.txt

depois, crie um arquivo runtime.txt com a versão do Python,

echo "python-3.13.3" > runtime.txt

por fim, defina as variáveis de ambiente PORT, DEEPL_SERVER_URL e DEEPL_AUTH_KEY com sua chave da API DeepL no workspace do render.com antes de definir o ponto de entrada,

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

Implantação

O servidor MCP está ativo e acessível no Render.com.

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

Você pode interagir com a API no URL acima.

Deploy on Render

Licença

MIT

TODOs

  • Adicionar mais casos de teste
  • Adicionar mais recursos
  • Adicionar mais documentação
  • Adicionar mais recursos de segurança
  • Adicionar mais logs
  • Adicionar mais monitoramento
  • Adicionar mais otimização de desempenho

Contribuição

Contribuições são bem-vindas! Se você tiver sugestões de melhorias ou novos recursos, abra uma issue ou envie um pull request.

Veja mais em Contribuição

Contato

Links