# UltraMsg MCP

Servidor **MCP (Model Context Protocol)** para la API de WhatsApp de [UltraMsg](https://ultramsg.com).
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

```bash
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`:

```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

```bash
# 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](https://github.com/modelcontextprotocol/python-sdk) + `requests`.

## Licencia

MIT.