Emule MCP

emule-mcp

Servidor MCP que expone el clásico cliente eMule a un agente de IA a través de su WebServer/Interfaz web integrada (puerto 4711 por defecto). Permite consultar y, más adelante, controlar eMule en lenguaje natural.

Actualmente expone herramientas para consultar el estado, buscar archivos, gestionar descargas y servidores.

Alcance y limitaciones

Dentro del alcance: consultar el estado, gestionar descargas, buscar archivos y administrar servidores a través del WebServer.

Fuera del alcance por ahora: los protocolos eD2k/Kad directamente, leer archivos .met, controlar la GUI nativa y clientes que no compartan esta interfaz web (como aMule/amuleweb).

El WebServer devuelve HTML basado en plantillas en lugar de JSON, por lo que los resultados se extraen de las páginas. Esto es frágil entre versiones y mods de eMule, y el servidor es secuencial: bloquea la GUI mientras atiende una solicitud, por lo que las solicitudes se serializan.

Requisitos

• Python 3.13 o superior.
• eMule ejecutándose con el WebServer habilitado (Preferences > WebServer) y una contraseña de administrador configurada.

Instalación

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

Configuración

Se configura mediante variables de entorno:

Variable	Requerida	Valor por defecto	Descripción
EMULE_WEB_PASSWORD	Sí	-	Contraseña para el WebServer de eMule.
EMULE_WEB_URL	No	http://127.0.0.1:4711	URL base del WebServer.
EMULE_WEB_USER	No	-	Nombre de usuario, solo para la variante multiusuario.
EMULE_WEB_TIMEOUT_MS	No	10000	Tiempo máximo por solicitud, en milisegundos.

Cómo iniciar la herramienta

El servidor habla MCP a través de stdio, por lo que normalmente lo lanza el propio agente como un proceso hijo. Para probarlo o iniciarlo manualmente:

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

Ambos scripts usan el intérprete .venv. Alternativas equivalentes:

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

Un servidor stdio no imprime nada y espera en stdin: ese es el comportamiento correcto.

Uso con un agente de IA

Registra el servidor en la configuración MCP de tu agente. Ejemplo 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"
      }
    }
  }
}

Cualquier host MCP (Claude Desktop, Cursor, VS Code) admite el mismo esquema command/args/env, apuntando al intérprete .venv y pasando la contraseña a través del entorno.

Una vez registrado, solicita la acción en lenguaje natural; por ejemplo:

Is eMule connected? use the emule_status tool

o

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

Herramientas disponibles

Herramienta	Parámetros	Descripción
emule_status	-	Estado de la conexión, velocidad de subida/bajada y estado de Kad.
emule_search	query; method (server|global|kademlia, por defecto server); file_type (Audio, Video, Image, Doc, Pro, Arc, Iso, opcional); limit (por defecto 25)	Busca archivos en eD2k/Kad y devuelve nombre, tamaño, fuentes, hash y enlace ed2k. Espera 10 s realizando reconsultas para recopilar resultados en lotes.
emule_download	ed2k	Añade un enlace eD2k a la cola de descargas y confirma que se registró.
emule_list_downloads	-	Lista las descargas actuales con nombre, tamaño, transferido, velocidad, fuentes, prioridad, categoría, estado, hash y enlace ed2k.
emule_list_servers	-	Lista los servidores conocidos con dirección, estado, usuarios, archivos y prioridad.
emule_connect	ip y port (ambos o ninguno; por defecto cualquier servidor disponible)	Conecta eMule a un servidor.
emule_disconnect	-	Desconecta del servidor actual.

Pruebas

.venv\Scripts\python -m pytest

Licencia

MIT. Consulta LICENSE.