UltraMsg MCP

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).

Related MCP server: mcp-evolution

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):

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: 34600000000@c.us (contacto) / ...@g.us (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.