Mautic

Se integra con la plataforma de automatización de marketing Mautic.

Documentación

Servidor MCP de Mautic

Un servidor completo del Protocolo de Contexto de Modelos (MCP) para la plataforma de automatización de marketing Mautic 7 (Edición Columba). Soporta endpoints tanto v1 (FOSRestBundle) como v2 (API Platform) con 68 herramientas.

Inicio Rápido

# Clone and setup
git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP
npm install

# Configure your Mautic credentials
cp .env.example .env
# Edit .env with your Mautic API credentials

# Build and run
npm run build

Luego agrega el servidor a tu configuración de MCP y comienza a usar comandos en lenguaje natural como:

"Buscar todos los contactos con gmail en su correo electrónico"
"Crear un nuevo proyecto para organizar los recursos de mi campaña del primer trimestre"
"Clonar la campaña 5 y exportarla para el entorno de preparación"
"Enviar la plantilla de correo 12 a su segmento asignado"

Novedades en v2.0 (Soporte para Mautic 7)

Proyectos (API v2)

Organiza recursos de marketing bajo una única estructura lógica usando los nuevos endpoints de API Platform v2 de Mautic 7.

list_projects, get_project, create_project, update_project, patch_project, delete_project

Importación/Exportación de Campañas

Mueve configuraciones completas de campañas entre entornos.

clone_campaign - Clona una campaña existente
export_campaign - Exporta datos de campaña con todos los recursos relacionados
import_campaign - Importa una campaña desde datos JSON

Analítica de Campañas

get_campaign_event_details - Métricas detalladas para eventos de campaña
get_campaign_graph_stats - Estadísticas de gráficos de campaña para rangos de fechas
get_campaign_map_stats - Estadísticas de mapas geográficos

Envío de Correos Basado en Segmentos

send_email_to_segment - Envía correos a segmentos asignados con adaptación de audiencia en tiempo real

Seguimiento de Respuestas de Correos

record_email_reply - Registra respuestas de correos mediante hash de seguimiento
get_email_graph_stats - Estadísticas de gráficos de correos para rangos de fechas

Aviso de Obsolescencia

Las clases de API de SMS han sido eliminadas en Mautic 7. Las herramientas list_sms y create_sms incluyen advertencias de obsolescencia.

Características

Autenticación

Autenticación OAuth2 con renovación automática de tokens
Gestión segura de credenciales mediante variables de entorno
Soporte de API dual: v1 (FOSRestBundle) y v2 (API Platform)

Gestión de Contactos (6 herramientas)

create_contact - Crea nuevos contactos con campos personalizados
update_contact - Actualiza información de contactos existentes
get_contact - Recupera detalles de contacto por ID o correo electrónico
search_contacts - Busca contactos con filtros y paginación
delete_contact - Elimina contactos de Mautic
add_contact_to_segment - Agrega contactos a segmentos específicos

Gestión de Campañas (13 herramientas)

list_campaigns - Obtiene todas las campañas con estado y estadísticas
get_campaign - Obtiene información detallada de campañas
create_campaign - Crea nuevas campañas
add_contact_to_campaign - Agrega contactos a campañas
create_campaign_with_automation - Crea campañas con automatización completa de eventos
execute_campaign - Ejecuta/activa campañas manualmente
get_campaign_contacts - Obtiene contactos en una campaña con su estado
clone_campaign - Clona una campaña existente (Mautic 7)
export_campaign - Exporta datos de campaña con recursos (Mautic 7)
import_campaign - Importa campaña desde datos JSON (Mautic 7)
get_campaign_event_details - Métricas de eventos de campaña (Mautic 7)
get_campaign_graph_stats - Estadísticas de gráficos de campaña (Mautic 7)
get_campaign_map_stats - Estadísticas geográficas de campaña (Mautic 7)

Operaciones de Correo (8 herramientas)

send_email - Envía correos a contactos específicos
list_emails - Obtiene todas las plantillas de correo y campañas
get_email - Obtiene información detallada de correos
create_email_template - Crea nuevas plantillas de correo
get_email_stats - Obtiene estadísticas de rendimiento de correos
send_email_to_segment - Envía correos a segmentos (Mautic 7)
record_email_reply - Registra respuesta de correo mediante hash de seguimiento (Mautic 7)
get_email_graph_stats - Estadísticas de gráficos de correos (Mautic 7)

Gestión de Formularios (3 herramientas)

list_forms - Obtiene todos los formularios con conteos de envíos
get_form - Obtiene detalles y campos de formularios
get_form_submissions - Obtiene datos de envíos de formularios

Gestión de Segmentos (3 herramientas)

list_segments - Obtiene todos los segmentos de contactos
create_segment - Crea nuevos segmentos de contactos con filtros
get_segment_contacts - Obtiene contactos en un segmento específico

Gestión de Contenido (7 herramientas)

list_assets - Obtiene todos los recursos (PDFs, imágenes, documentos)
get_asset - Obtiene detalles de recursos por ID
create_asset - Crea nuevos recursos (locales o remotos)
list_pages - Obtiene todas las páginas de destino
create_page - Crea nuevas páginas de destino
list_sms - Obtiene todas las plantillas de SMS [OBSOLETO en Mautic 7]
create_sms - Crea plantillas de SMS [OBSOLETO en Mautic 7]

Entidades de Negocio (10 herramientas)

list_companies - Obtiene todas las empresas
create_company - Crea nuevas empresas
add_contact_to_company - Asocia contactos con empresas
create_note - Agrega notas a contactos o empresas
get_contact_notes - Obtiene todas las notas de un contacto
list_tags - Obtiene todas las etiquetas disponibles
create_tag - Crea nuevas etiquetas
add_contact_tags - Agrega etiquetas a contactos
list_categories - Obtiene todas las categorías
create_category - Crea nuevas categorías

Características Avanzadas (7 herramientas)

add_contact_points - Agrega puntos a contactos
subtract_contact_points - Resta puntos de contactos
list_stages - Obtiene todas las etapas del ciclo de vida
change_contact_stage - Cambia la etapa del ciclo de vida de un contacto
list_contact_fields - Obtiene todos los campos personalizados de contactos
create_contact_field - Crea nuevos campos personalizados de contactos
get_contact_activity - Obtiene el historial de interacciones de contactos

Integración y Automatización (5 herramientas)

list_webhooks - Obtiene todos los webhooks
create_webhook - Crea nuevos webhooks
upload_file - Sube archivos a Mautic
list_reports - Obtiene todos los informes
create_report - Crea informes personalizados

Gestión de Proyectos - API v2 (6 herramientas, Mautic 7)

list_projects - Lista todos los proyectos
get_project - Obtiene detalles de proyectos
create_project - Crea un nuevo proyecto
update_project - Actualiza completamente un proyecto existente
patch_project - Actualiza parcialmente un proyecto
delete_project - Elimina un proyecto

Instalación

Requisitos Previos

Node.js (v16 o superior)
npm o yarn
Acceso a una instancia de Mautic 7 con credenciales de API

Configuración

Clona el repositorio:

git clone https://github.com/Cbrown35/mantic-MCP.git
cd mantic-MCP

Instala las dependencias:
```
npm install
```

Configura las variables de entorno:

cp .env.example .env

Edita .env y completa tus credenciales de API de Mautic:

MAUTIC_BASE_URL=https://your-mautic-instance.com/api/
MAUTIC_CLIENT_ID=your_client_id_here
MAUTIC_CLIENT_SECRET=your_client_secret_here
MAUTIC_TOKEN_ENDPOINT=https://your-mautic-instance.com/oauth/v2/token

Compila el servidor:
```
npm run build
```

Configura los ajustes de MCP: Agrega el servidor a tu archivo de configuración de MCP:

{
  "mcpServers": {
    "mautic-server": {
      "command": "node",
      "args": ["/path/to/mautic-server/build/index.js"],
      "env": {
        "MAUTIC_BASE_URL": "https://your-mautic-instance.com/api/",
        "MAUTIC_CLIENT_ID": "your_client_id",
        "MAUTIC_CLIENT_SECRET": "your_client_secret",
        "MAUTIC_TOKEN_ENDPOINT": "https://your-mautic-instance.com/oauth/v2/token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Arquitectura

Soporte de API Dual

Mautic 7 tiene una arquitectura de API de tres niveles:

Nivel	Propósito	Endpoints
API Platform 4.x	Nuevos endpoints REST v2 (JSON-LD/Hydra)	`/api/v2/projects`
FOSRestBundle	Endpoints v1 existentes	`/api/contacts`, `/api/campaigns`, etc.
FOSOAuthServerBundle	Autenticación OAuth2	`/oauth/v2/token`

El servidor MCP gestiona automáticamente ambas versiones de API. Los endpoints v1 usan MAUTIC_BASE_URL configurado directamente, mientras que los endpoints v2 se derivan automáticamente.

Estructura del Proyecto

src/
├── index.ts              # Entry point: server setup and startup
├── types/                # TypeScript interfaces
│   ├── common.ts         # Shared types (OAuth2Token, ToolResult, etc.)
│   ├── contacts.ts       # MauticContact interface
│   ├── campaigns.ts      # MauticCampaign interface
│   ├── emails.ts         # MauticEmail interface
│   ├── forms.ts          # MauticForm interface
│   ├── segments.ts       # MauticSegment interface
│   └── projects.ts       # MauticProject interface (Mautic 7)
├── api/
│   └── client.ts         # Dual API client (v1 + v2) with OAuth2
└── tools/
    ├── index.ts           # Tool registry and dispatch
    ├── contacts.ts        # Contact tools
    ├── campaigns.ts       # Campaign tools (includes Mautic 7 additions)
    ├── emails.ts          # Email tools (includes Mautic 7 additions)
    ├── forms.ts           # Form tools
    ├── segments.ts        # Segment tools
    ├── projects.ts        # Project tools (Mautic 7 API v2)
    ├── content.ts         # Asset, page, and SMS tools
    ├── business.ts        # Company, note, tag, and category tools
    ├── advanced.ts        # Points, stages, fields, and activity tools
    └── integration.ts     # Webhook, file, and report tools

Configuración

Variables de Entorno

Variable	Descripción	Ejemplo
`MAUTIC_BASE_URL`	Tu URL base de API de Mautic	`https://your-mautic.com/api/`
`MAUTIC_CLIENT_ID`	ID de Cliente OAuth2	`1_abc123...`
`MAUTIC_CLIENT_SECRET`	Secreto de Cliente OAuth2	`secret123...`
`MAUTIC_TOKEN_ENDPOINT`	Endpoint de Token OAuth2	`https://your-mautic.com/oauth/v2/token`

Obtención de Credenciales de API de Mautic

Inicia sesión en tu instancia de Mautic como administrador
Ve a Configuración > Configuración > Ajustes de API
Habilita el acceso a la API
Ve a Configuración > Credenciales de API
Crea una nueva credencial de API con autorización OAuth2
Anota el ID de Cliente y el Secreto de Cliente

Manejo de Errores

El servidor incluye manejo integral de errores:

Renovación automática de tokens OAuth2
Mensajes de error detallados de formatos de API v1 y v2
Manejo elegante de fallos de autenticación
Lógica de reintento para errores transitorios

Seguridad

Todas las credenciales se almacenan como variables de entorno
Los tokens OAuth2 se renuevan automáticamente
No se registran ni exponen datos sensibles
Comunicación HTTPS segura con la API de Mautic

Desarrollo

Para modificar o extender el servidor:

Edita el código fuente en el directorio src/
Agrega nuevas herramientas creando un archivo en src/tools/ e importándolo en src/tools/index.ts
Compila el servidor: npm run build
Prueba con el Inspector de MCP: npm run inspector

Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta el repositorio para conocer las pautas de contribución.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

Construido con el SDK del Protocolo de Contexto de Modelos v1.26.0
Se integra con Mautic 7 (Edición Columba)