Servidor MCP instantáneo

Servidor MCP para la API Instantly v2 , que proporciona acceso a campañas de correo electrónico y funcionalidades de gestión de clientes potenciales.

Acerca de la API instantánea

La API Instantly v2 es una API RESTful que proporciona acceso a varios recursos y funciones de la plataforma Instantly, incluidos:

• Gestión de campañas

• Gestión de clientes potenciales

• Manejo y verificación de correo electrónico

• Analítica

• Gestión de cuentas

• Gestión de listas de bloqueo

• Y más

Este servidor MCP implementa un subconjunto de estos puntos finales para proporcionar un acceso fácil a las funciones más utilizadas.

Referencia de API

La documentación completa de Instantly API v2 está disponible en:

• Explorador de API

• Esquemas de API

• Puntos finales de análisis

La URL base para todas las solicitudes de API es: https://api.instantly.ai/api/v2

Herramientas

Este servidor MCP implementa las siguientes herramientas que se asignan a los puntos finales de Instantly API v2:

1. instantly_create_lead

   • Punto final de API : POST /api/v2/leads

   • Crear un nuevo cliente potencial

   • Entradas:

     • email (cadena)

     • first_name (cadena opcional)

     • last_name (cadena opcional)

     • company_name (cadena opcional)

     • campaign (cadena opcional, uuid)

     • list_id (cadena opcional, uuid)

     • personalization (cadena opcional)

     • website (cadena opcional)

     • phone (cadena opcional)

     • custom_variables (objeto opcional)

2. instantly_get_lead

   • Punto final de API : GET /api/v2/leads/{id}

   • Obtener detalles de un cliente potencial por ID

   • Entrada: id (cadena, uuid)

   • Devoluciones: detalles del cliente potencial

3. instantly_list_leads

   • Punto final de API : POST /api/v2/leads/list

   • Lista de clientes potenciales con filtros opcionales

   • Entradas:

     • campaign (cadena opcional, uuid)

     • list_id (cadena opcional, uuid)

     • limit (número opcional)

     • starting_after (cadena opcional)

   • Devoluciones: matriz de pistas

4. instantly_update_lead

   • Punto final de API : PATCH /api/v2/leads/{id}

   • Actualizar la información de un cliente potencial

   • Entradas:

     • id (cadena, uuid)

     • first_name (cadena opcional)

     • last_name (cadena opcional)

     • company_name (cadena opcional)

     • personalization (cadena opcional)

     • website (cadena opcional)

     • phone (cadena opcional)

     • custom_variables (objeto opcional)

5. instantly_delete_lead

   • Punto final de API : DELETE /api/v2/leads/{id}

   • Eliminar un cliente potencial

   • Entrada: id (cadena, uuid)

6. instantly_list_campaigns

   • Punto final de API : GET /api/v2/campaigns

   • Lista de campañas con soporte de paginación

   • Entradas:

     • limit (número opcional, predeterminado 5, máximo 100)

     • starting_after (cadena opcional): para la paginación, utilice el valor next_starting_after de la respuesta anterior.

     • status (número opcional): filtra campañas por estado (0: Borrador, 1: Activo, 2: En pausa, 3: Completado, 4: Subsecuencias en ejecución)

   • Devoluciones: matriz de campañas con información de paginación

   • Paginación:

     • Primera solicitud: Llamar sin starting_after

     • Páginas siguientes: utilice el valor next_starting_after de la respuesta anterior

     • Cuando no haya más páginas, la respuesta no contendrá un valor next_starting_after

   • Ejemplo: Para obtener solo campañas activas, use status: 1

7. instantly_get_campaign

   • Punto final de la API : GET /api/v2/campaigns/{id}

   • Obtener detalles de una campaña

   • Entrada: id (cadena, uuid)

   • Devoluciones: detalles de la campaña

8. instantly_get_warmup_analytics

   • Punto final de la API : POST /api/v2/accounts/warmup-analytics

   • Obtenga análisis de calentamiento para cuentas de correo electrónico específicas

   • Entrada: emails (matriz de cadenas)

   • Devoluciones: puntuaciones de salud y métricas para el rendimiento del calentamiento del correo electrónico

   • Útil para supervisar la capacidad de entrega del correo electrónico y el estado de la cuenta.

9. instantly_test_account_vitals

   • Punto final de la API : POST /api/v2/accounts/test/vitals

   • Pruebe el estado y la conectividad de las cuentas de correo electrónico en su espacio de trabajo Instantly

   • Entrada: accounts (matriz de cadenas): puede probar varias direcciones de correo electrónico a la vez

   • Devoluciones:

     • Estado general de la prueba

     • Resumen de cuentas exitosas y fallidas

     • Información detallada de cada cuenta, incluidos los detalles del proveedor

     • Recomendaciones para la solución de problemas de cuentas fallidas

   • Ayuda a identificar problemas con la configuración de la cuenta de correo electrónico, la autenticación y el acceso a la API.

   • Ejemplo: {"accounts": ["user@example.com", "sales@company.com"]}

10. instantly_get_campaign_analytics

• Punto final de API : GET /api/v2/campaigns/analytics

• Obtenga métricas de rendimiento de las campañas durante un período de tiempo específico

• Entradas:

  • id (cadena opcional): ID de campaña para una campaña específica

  • start_date (cadena) - Fecha de inicio en formato AAAA-MM-DD

  • end_date (cadena) - Fecha de finalización en formato AAAA-MM-DD

• Devoluciones: métricas completas que incluyen tasas de apertura, tasas de respuesta, recuentos de clientes potenciales y datos de oportunidades

Puntos finales de análisis

La API Instantly proporciona potentes puntos finales de análisis para supervisar el rendimiento de sus campañas y cuentas de correo electrónico:

1. Obtener análisis de calentamiento

   • Punto final de la API : POST /api/v2/accounts/warmup-analytics

   • Descripción : Recupera datos de análisis de calentamiento para cuentas de correo electrónico específicas

   • Ámbitos obligatorios : accounts:read , accounts:all , all:read o all:all

   • Cuerpo de la solicitud :

     { "emails": ["user@example.com"] }

   • Respuesta : proporciona datos diarios y agregados sobre correos electrónicos enviados, ubicación en la bandeja de entrada, ubicación en correo no deseado y correos electrónicos recibidos, junto con puntajes de salud para cada cuenta.

2. Datos vitales de la cuenta de prueba

   • Punto final de la API : POST /api/v2/accounts/test/vitals

   • Descripción : Prueba la salud y la conectividad de las cuentas de correo electrónico.

   • Ámbitos obligatorios : accounts:read , accounts:all , all:read o all:all

   • Cuerpo de la solicitud :

     { "accounts": ["user@example.com"] }

   • Respuesta : Devuelve listas de éxito y fracaso con información detallada sobre el estado de la cuenta y cualquier problema detectado.

3. Obtener análisis de campañas

   • Punto final de API : GET /api/v2/campaigns/analytics

   • Descripción : Recupera métricas de rendimiento de una o varias campañas.

   • Parámetros de consulta :

     • id (opcional): ID de campaña para una campaña específica

     • start_date : Fecha de inicio del período de análisis

     • end_date : Fecha de finalización del período de análisis

   • Respuesta : Devuelve estadísticas completas de la campaña, que incluyen:

     • Recuento total de clientes potenciales

     • Recuento de clientes potenciales contactados

     • Recuento de aperturas de correo electrónico

     • Número de respuestas

     • Recuento de rebotes

     • Recuento de personas no suscritas

     • Conteo completado

     • Conteo de correos electrónicos enviados

     • Conteo de nuevos clientes potenciales contactados

     • Oportunidades totales

     • Valor total de oportunidad

Para obtener información detallada sobre los parámetros de solicitud y los formatos de respuesta, consulte la documentación de la API de Instantly Analytics .

Puntos finales de API adicionales de Instantly

La API Instantly v2 incluye muchos otros puntos finales no implementados en este servidor MCP, incluidos:

• Gestión de campañas :

  • Crear campaña: POST /api/v2/campaigns

  • Activar campaña: POST /api/v2/campaigns/{id}/activate

  • Pausar campaña: POST /api/v2/campaigns/{id}/pause

  • Campaña de actualización: PATCH /api/v2/campaigns/{id}

• Correo electrónico :

  • Responder al correo electrónico: POST /api/v2/emails/reply

  • Lista de correos electrónicos: GET /api/v2/emails

  • Obtener correo electrónico: GET /api/v2/emails/{id}

  • Contar correos electrónicos no leídos: GET /api/v2/emails/unread/count

• Gestión de cuentas :

  • Estos puntos finales ya están disponibles como herramientas en este servidor MCP. Consulte la sección "Herramientas de administración de cuentas" a continuación.

• Verificación de correo electrónico :

  • Verificar correo electrónico: POST /api/v2/email-verification

• Listas principales :

  • Crear lista: POST /api/v2/lead-lists

  • Lista de listas de clientes potenciales: GET /api/v2/lead-lists

Para obtener una referencia completa de todos los puntos finales disponibles, consulte el Explorador de API Instantly .

Configuración

Clave API

Obtén una clave API instantánea desde la configuración de tu cuenta instantánea:

1. Vaya a integraciones en su panel de control de Instantly

2. Haga clic en la sección "Claves API" en la barra lateral izquierda

3. Haga clic en el botón "Crear clave API"

4. Ingrese un nombre para su clave API

5. Seleccione los ámbitos a los que desea que esta clave tenga acceso

6. Crea y copia tu clave API (nota: solo se mostrará una vez)

Uso con Claude Desktop

Agregue lo siguiente a su claude_desktop_config.json :

Estibador

NPX

Construir

Compilación de Docker:

Autenticación

La API Instantly v2 utiliza autenticación con token de portador. Su clave API debe incluirse en el encabezado de autorización de todas las solicitudes:

El servidor MCP maneja esto automáticamente cuando usted proporciona su clave API a través de la variable de entorno.

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.

Herramientas de gestión de cuentas

Este servidor MCP implementa las siguientes herramientas para la gestión de cuentas:

1. instantly_create_account

   • Punto final de API : POST /api/v2/accounts

   • Crea una nueva cuenta de correo electrónico en Instantly

   • Entradas:

     • email (cadena): Dirección de correo electrónico de la cuenta

     • first_name (cadena): Nombre asociado a la cuenta

     • last_name (cadena): Apellido asociado a la cuenta

     • provider_code (número): Código del proveedor (1: IMAP/SMTP personalizado, 2: Google, 3: Microsoft, 4: AWS)

     • imap_username (cadena): nombre de usuario IMAP

     • imap_password (cadena): contraseña IMAP

     • imap_host (cadena): host IMAP (por ejemplo, imap.gmail.com)

     • imap_port (número): puerto IMAP (por ejemplo, 993)

     • smtp_username (cadena): nombre de usuario SMTP

     • smtp_password (cadena): contraseña SMTP

     • smtp_host (cadena): host SMTP (por ejemplo, smtp.gmail.com)

     • smtp_port (número): puerto SMTP (por ejemplo, 587)

     • daily_limit (número opcional): límite diario de envío de correos electrónicos

     • tracking_domain_name (cadena opcional): nombre de dominio de seguimiento

2. instantly_list_accounts

   • Punto final de API : GET /api/v2/accounts

   • Enumere cuentas de correo electrónico al instante con paginación automática

   • Entradas:

     • limit (número opcional): la cantidad de cuentas que se devolverán por página (máximo 100, predeterminado 10)

     • starting_after (cadena opcional): el ID del último elemento en la página anterior (se utiliza para la paginación).

     • search (cadena opcional): término de búsqueda para filtrar cuentas

     • status (número opcional): Filtro de estado (1: Activo, 2: En pausa, -1: Error de conexión, -2: Error de rebote suave, -3: Error de envío)

     • provider_code (número opcional): filtro de código de proveedor (1: IMAP/SMTP personalizado, 2: Google, 3: Microsoft, 4: AWS)

     • fetch_all (booleano opcional): Si se recuperan automáticamente todas las páginas y se proporciona un resumen completo. Úselo para obtener información sobre todas las cuentas.

   • Paginación:

     • Comportamiento predeterminado: Devuelve una sola página de resultados con un enlace a la página siguiente

     • Con fetch_all=true : recupera automáticamente todas las páginas y devuelve un resumen completo de todas las cuentas, incluidas:

       • Recuento total de cuentas

       • Distribución de cuentas por proveedor

       • Distribución de cuentas por estado

       • Muestra de cuentas de referencia

3. instantly_get_account

   • Punto final de la API : GET /api/v2/accounts/{email}

   • Obtenga detalles de una cuenta de correo electrónico específica al instante

   • Entrada: email (cadena): Dirección de correo electrónico de la cuenta a recuperar

4. instantly_update_account

   • Punto final de API : PATCH /api/v2/accounts/{email}

   • Actualizar una cuenta de correo electrónico existente al instante

   • Entradas:

     • email (cadena): Dirección de correo electrónico de la cuenta a actualizar

     • first_name (cadena opcional): Nombre asociado a la cuenta

     • last_name (cadena opcional): Apellido asociado a la cuenta

     • daily_limit (número opcional): límite diario de envío de correos electrónicos

     • tracking_domain_name (cadena opcional): nombre de dominio de seguimiento

     • skip_cname_check (booleano opcional): si se debe omitir la verificación de CNAME para el seguimiento del dominio

     • remove_tracking_domain (booleano opcional): si se debe eliminar el dominio de seguimiento de la cuenta

5. instantly_delete_account

   • Punto final de la API : DELETE /api/v2/accounts/{email}

   • Eliminar una cuenta de correo electrónico de forma instantánea

   • Entrada: email (cadena): Dirección de correo electrónico de la cuenta que se eliminará

6. instantly_pause_account

   • Punto final de API : POST /api/v2/accounts/{email}/pause

   • Pausar una cuenta de correo electrónico al instante

   • Entrada: email (cadena): Dirección de correo electrónico de la cuenta que se pausará

7. instantly_resume_account

   • Punto final de API : POST /api/v2/accounts/{email}/resume

   • Reanudar una cuenta de correo electrónico pausada al instante

   • Entrada: email (cadena): Dirección de correo electrónico de la cuenta a reanudar

Estado de las pruebas de herramientas

Hemos probado exhaustivamente todas las herramientas implementadas en este servidor MCP para garantizar su correcto funcionamiento con la API Instantly v2. A continuación, se muestra un resumen del estado de las pruebas:

Para obtener más detalles sobre el proceso de prueba y los resultados, consulte Testing.md en el repositorio.

Problemas conocidos

• La herramienta instantly_list_leads actualmente devuelve un error de API de "Dirección de correo electrónico no válida" al intentar listar clientes potenciales sin un filtro de correo electrónico específico. Hemos probado varias estrategias para solucionar este problema, incluyendo:

  • Uso del parámetro de matriz contacts para búsquedas de correo electrónico

  • Implementación de reintentos automáticos con cuerpos de solicitud vacíos

  • Varios enfoques de formato de parámetros Continuaremos trabajando para resolver este problema en futuras versiones.

Configuración para el desarrollo

Si quieres contribuir a este proyecto o ejecutarlo localmente para su desarrollo:

1. Clonar el repositorio:

   git clone https://github.com/bcharleson/Instantly-MCP.git cd Instantly-MCP

2. Instalar dependencias:

   npm install

3. Cree un archivo .env en el directorio raíz con su clave API de Instantly:

   INSTANTLY_API_KEY=your_api_key_here

   ⚠️ Importante : Nunca envíes tu archivo .env ni tu clave API al control de versiones. El archivo .env se incluye en .gitignore para evitar envíos accidentales.

4. Construir el proyecto:

   npm run build

5. Ejecutar el servidor:

   node dist/index.js

Contribuyendo

¡Agradecemos sus contribuciones! Si desea colaborar:

1. Bifurcar el repositorio

2. Crear una rama de características ( git checkout -b feature/amazing-feature )

3. Realiza tus cambios

4. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

5. Empujar a la rama ( git push origin feature/amazing-feature )

6. Abrir una solicitud de extracción

Antes de enviar una solicitud de extracción, asegúrese de lo siguiente:

• Su código sigue el estilo de codificación del proyecto.

• Ha agregado pruebas para nuevas funcionalidades

• Todas las pruebas pasan

• Has actualizado la documentación si es necesario.