Ultramsg

Servidor MCP (Model Context Protocol) para la API de WhatsApp de UltraMsg. Permite a Claude (Desktop / Cowork / cualquier cliente MCP) enviar y leer mensajes de WhatsApp: texto, imágenes, documentos, audio, notas de voz, vídeo, stickers, ubicaciones, contactos y reacciones, además de consultar el estado de la instancia, chats, contactos y grupos.

Genérico y portable: no incluye ninguna credencial. Configura tu instancia y token por variables de entorno.

---

Endpoints / URL base

UltraMsg expone una API REST por instancia:

https://api.ultramsg.com/{INSTANCE_ID}/...

Tu INSTANCE_ID y TOKEN están en el panel de UltraMsg (sección Instance).

---

Instalación

git clone https://github.com/<usuario>/ultramsg-mcp.git
cd ultramsg-mcp
pip install -r requirements.txt

Configuración

Por variables de entorno (recomendado):

Variable	Obligatoria	Descripción
ULTRAMSG_INSTANCE_ID	✅	ID de instancia, p.ej. instanceXXXXXX
ULTRAMSG_TOKEN	✅	Token de la instancia
ULTRAMSG_BASE_URL	❌	Por defecto https://api.ultramsg.com
ULTRAMSG_ALLOW_CRITICAL	❌	1 para habilitar acciones críticas (off por defecto)
ULTRAMSG_ALLOWED_RECIPIENTS	❌	Lista de números permitidos como destinatario (coma-separada). Vacío = cualquiera
PYTHONUTF8	recomendado	1 en Windows para evitar errores de codificación

Alternativa: copia config.json.example a config.json (excluido por .gitignore) y rellena tus datos.

Registro en Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "ultramsg": {
      "command": "python",
      "args": ["C:/ruta/a/ultramsg-mcp/server.py"],
      "env": {
        "ULTRAMSG_INSTANCE_ID": "instanceXXXXXX",
        "ULTRAMSG_TOKEN": "tu_token",
        "PYTHONUTF8": "1"
      }
    }
  }
}

Reinicia Claude Desktop tras editar el config.

---

Herramientas (27)

Lectura (READ)

• ultramsg_instance_status — estado de la instancia (conectada, batería…)
• ultramsg_instance_me — cuenta de WhatsApp vinculada
• ultramsg_instance_settings — configuración (webhooks, delays…)
• ultramsg_list_messages — lista mensajes (filtro por estado, paginado)
• ultramsg_message_statistics — estadísticas de envío
• ultramsg_list_chats — chats
• ultramsg_chat_messages — mensajes de un chat
• ultramsg_list_contacts — contactos
• ultramsg_check_number — comprueba si un número está en WhatsApp
• ultramsg_list_groups — grupos
• ultramsg_get_group — detalle de un grupo

Envíos (WRITE)

• ultramsg_send_text — texto
• ultramsg_send_image — imagen (URL o base64) + caption
• ultramsg_send_document — documento (PDF, docx…)
• ultramsg_send_audio — audio (mp3)
• ultramsg_send_voice — nota de voz (ogg/opus)
• ultramsg_send_video — vídeo
• ultramsg_send_sticker — sticker (webp)
• ultramsg_send_location — ubicación (lat/lng)
• ultramsg_send_contact — compartir contacto
• ultramsg_send_reaction — reaccionar a un mensaje

Críticas (CRITICAL — requieren ULTRAMSG_ALLOW_CRITICAL=1)

• ultramsg_delete_message — borrar mensaje enviado
• ultramsg_clear_messages — vaciar cola/historial
• ultramsg_instance_restart — reiniciar instancia
• ultramsg_instance_logout — cerrar sesión (desvincula el teléfono)
• ultramsg_block_contact / ultramsg_unblock_contact

Las acciones críticas están bloqueadas por defecto porque pueden desconectar o alterar la instancia de WhatsApp. Se habilitan explícitamente con ULTRAMSG_ALLOW_CRITICAL=1.

---

Formato de destinatario

• Número con prefijo de país: 34600000000
• O chatId: [email protected] (contacto) / [email protected] (grupo)

El servidor normaliza +, espacios y guiones automáticamente.

---

Pruebas

# requiere credenciales + un número de prueba propio
export TEST_TO=34600000000
python test_mcp.py          # cobertura de los 27 endpoints (READ/WRITE/CRITICAL)
python test_handshake.py    # handshake MCP por stdio (initialize + tools/list)

Stack

Python 3 + FastMCP + requests.

Licencia

MIT.