Emule MCP

emule-mcp

Servidor MCP que expõe o clássico cliente eMule a um agente de IA através de sua WebServer/Webinterface integrada (porta 4711 por padrão). Ele permite consultar e, futuramente, controlar o eMule em linguagem natural.

Atualmente, ele expõe ferramentas para consultar status, buscar arquivos, gerenciar downloads e servidores.

Escopo e limitações

No escopo: consultar status, gerenciar downloads, buscar arquivos e administrar servidores através do WebServer.

Fora do escopo por enquanto: os protocolos eD2k/Kad diretamente, leitura de arquivos .met, controle da GUI nativa e clientes que não compartilham esta Webinterface (como aMule/amuleweb).

O WebServer retorna HTML com modelos em vez de JSON, então os resultados são extraídos das páginas. Isso é frágil entre versões e mods do eMule, e o servidor é sequencial: ele bloqueia a GUI enquanto atende uma solicitação, então as solicitações são serializadas.

Requisitos

• Python 3.13 ou superior.
• eMule em execução com o WebServer habilitado (Preferences > WebServer) e uma senha de administrador configurada.

Instalação

python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"   # Windows
# .venv/bin/python -m pip install -e ".[dev]"      # Linux/macOS

Configuração

Ele é configurado através de variáveis de ambiente:

Variável	Obrigatória	Padrão	Descrição
EMULE_WEB_PASSWORD	Sim	-	Senha para o WebServer do eMule.
EMULE_WEB_URL	Não	http://127.0.0.1:4711	URL base do WebServer.
EMULE_WEB_USER	Não	-	Nome de usuário, apenas para a variante multiusuário.
EMULE_WEB_TIMEOUT_MS	Não	10000	Tempo máximo por solicitação, em milissegundos.

Como iniciar a ferramenta

O servidor fala MCP via stdio, então ele normalmente é iniciado pelo próprio agente como um processo filho. Para testá-lo ou iniciá-lo manualmente:

run.bat            # Windows
./run.sh           # Linux/macOS

Ambos os scripts usam o interpretador .venv. Alternativas equivalentes:

.venv\Scripts\python -m emule_mcp.server   # Windows
emule-mcp                                  # console script, after installing the package

Um servidor stdio não imprime nada e aguarda em stdin: esse é o comportamento correto.

Uso com um agente de IA

Registre o servidor na configuração MCP do seu agente. Exemplo para opencode (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "emule": {
      "type": "local",
      "command": [
        "<path-to-project>/.venv/Scripts/python.exe",
        "-m",
        "emule_mcp.server"
      ],
      "environment": {
        "EMULE_WEB_PASSWORD": "your-password"
      }
    }
  }
}

Qualquer host MCP (Claude Desktop, Cursor, VS Code) suporta o mesmo esquema command/args/env, apontando para o interpretador .venv e passando a senha através do ambiente.

Após o registro, peça a ação em linguagem natural; por exemplo:

Is eMule connected? use the emule_status tool

ou

I am in Spain: nonprofit peer-to-peer (P2P) file sharing was decriminalized by the 2015
reform of the Penal Code (arts. 270 and 271). Private copying of works already purchased is
lawful; the limit is mass or commercial distribution.

Download the latest song by ...., use the emule_download tool

Ferramentas disponíveis

Ferramenta	Parâmetros	Descrição
emule_status	-	Estado da conexão, velocidade de upload/download e status do Kad.
emule_search	query; method (server|global|kademlia, padrão server); file_type (Audio, Video, Image, Doc, Pro, Arc, Iso, opcional); limit (padrão 25)	Busca arquivos no eD2k/Kad e retorna nome, tamanho, fontes, hash e link ed2k. Aguarda 10 s fazendo novas buscas para coletar resultados em lotes.
emule_download	ed2k	Adiciona um link eD2k à fila de downloads e confirma que foi registrado.
emule_list_downloads	-	Lista os downloads atuais com nome, tamanho, transferido, velocidade, fontes, prioridade, categoria, estado, hash e link ed2k.
emule_list_servers	-	Lista os servidores conhecidos com endereço, estado, usuários, arquivos e prioridade.
emule_connect	ip e port (ambos ou nenhum; padrão para qualquer servidor disponível)	Conecta o eMule a um servidor.
emule_disconnect	-	Desconecta do servidor atual.

Testes

.venv\Scripts\python -m pytest

Licença

MIT. Consulte LICENSE.