instantly-ai-mcp

Un servidor MCP para la API REST v2 de Instantly.ai que codifica lo que la API realmente hace en lugar de confiar en lo que dicen sus documentos. Cada peculiaridad que aparece a continuación fue reproducida contra la API en vivo, no copiada de un registro de cambios ni de una publicación en un foro, y se mantiene verificada: npm run verify-gotchas vuelve a sondear la cuenta en vivo bajo demanda y marca cualquier afirmación cuyo comportamiento en el mundo real se haya desviado de lo documentado aquí (consulta Por qué esta tabla está verificada por máquina — es una verificación manual, no parte de CI).

Las peculiaridades

Esta tabla es la razón de que exista el repositorio. Todo servidor construido contra esta API eventualmente redescubre estas cosas de la manera difícil — normalmente mirando un error que parece otra cosa. Capturado en vivo el 2026-08-21; consulta Por qué esta tabla está verificada por máquina para saber cómo se mantiene honesta.

Notas sobre las filas interesantes:

• #3 — la sonda en vivo envió campaign_ids: [id] y obtuvo 5 leads, los 5 pertenecientes a otras campañas. El parámetro no solo se ignora, es silenciosamente un filtro sin efecto; el parámetro singular campaign es el que realmente limita la consulta. list_leads verifica el propio campo campaign de cada lead devuelto exactamente por esta razón y advierte en lugar de confiar en el filtro.

• #4 — esto se registró como SE MANTIENE el 2026-08-17 y cambió a REFUTADO el 2026-08-21. ?id= ahora filtra correctamente las analíticas a la única campaña. Consulta abajo por qué ese cambio es el punto central de este repositorio.

• #5 — NO VERIFICABLE el 2026-08-17 (no existía una campaña en borrador en la cuenta para probar), luego confirmado como SE MANTIENE por la suite de integración en vivo (INSTANTLY_LIVE_TEST=1), que crea una campaña en borrador desechable y confirma que el /campaigns/analytics sin filtrar la omite. El SE MANTIENE anterior está verificado de esa manera, no por la sonda de solo lectura de verify-gotchas: esa sonda devuelve NO VERIFICABLE cuando no existe ya una campaña en borrador en la cuenta (nunca crea una), por lo que ejecutarla contra una cuenta sin borradores se espera que diga "no se pudo volver a verificar", no que contradiga esta fila. list_campaigns lee de GET /campaigns por esta razón — ese endpoint sí incluye borradores.

• #6, #7, #8 son NO VERIFICABLE por la sonda de solo lectura por principio, no por accidente: #6 y #7 requerirían una escritura en vivo (crear una campaña / webhook) que el script de la sonda deliberadamente nunca realiza contra una cuenta real, y #8 es un problema intermitente de consistencia de lectura que no se puede forzar bajo demanda. NO VERIFICABLE es un resultado real y honesto aquí — consulta abajo.

Por qué esta tabla está verificada por máquina

Una lista de peculiaridades mantenida a mano se pudre. La afirmación #4 anterior es la prueba: se registró como SE MANTIENE el 2026-08-17 y fue refutada cuatro días después, el 2026-08-21, cuando Instantly aparentemente arregló el parámetro ?id= en el servidor. Cuatro días no es una cola larga — es lo rápido que una API no documentada puede moverse bajo una suposición escrita.

npm run verify-gotchas vuelve a ejecutar la sonda de cada afirmación contra la API en vivo e imprime una tabla de cinco columnas (#, Afirmación, Veredicto, Observado, Última verificación) — un superconjunto del resumen de tres columnas anterior, que lleva la evidencia cruda de la sonda en vivo y la fecha en que se ejecutó. Eso no tiene la misma forma que la tabla anterior; no esperes una coincidencia byte por byte.

Cada afirmación también lleva un veredicto esperado documentado (SE MANTIENE para #1–#3 y #5, REFUTADO para #4, NO VERIFICABLE para #6–#8) — el estado actualmente documentado, es decir, lo que este README dice hoy. El script sale con código distinto de cero solo cuando el veredicto real de una sonda ha cambiado genuinamente de esa expectativa (por ejemplo, un SE MANTIENE documentado vuelve como REFUTADO), e imprime exactamente qué afirmación se desvió y en qué dirección. Reconfirmar una afirmación ya documentada como REFUTADO (como #4) no es una desviación y no hace fallar la ejecución — solo un cambio nuevo lo hace.

NO VERIFICABLE es un resultado real que el script informa honestamente, no un fallo que encubre, y nunca cuenta como desviación en ninguna dirección. Algunas afirmaciones genuinamente no se pueden verificar con una sonda segura, de solo lectura y no destructiva (consulta #6–#8 arriba); el script lo dice en lugar de adivinar o omitir silenciosamente. #5 es el caso más claro: su SE MANTIENE documentado proviene de la suite de integración en vivo, no de esta sonda, por lo que la sonda que devuelve NO VERIFICABLE (no existe una campaña en borrador en este momento) se informa como "no se pudo volver a verificar" — no como un fallo.

INSTANTLY_API_KEY=your-key npm run verify-gotchas

verify-gotchas se ejecuta manualmente, no está conectado a CI — consulta .github/workflows/ci.yml, solo ejecuta build, typecheck y test. Es una elección deliberada, no un descuido: CI no tiene una clave de API en vivo (el script se omite limpiamente sin una, imprime un mensaje y sale con 0 — consulta el inicio de scripts/verify-gotchas.ts — por lo que de todos modos sería un no-op silencioso allí), y este script existe para tocar los endpoints de lectura de una cuenta real, lo que el CI de un repositorio no tiene por qué hacer sin supervisión. Ejecútalo localmente contra tu propia cuenta cuando quieras una lectura fresca.

Instalación

{
  "mcpServers": {
    "instantly": {
      "command": "npx",
      "args": ["-y", "instantly-ai-mcp"],
      "env": { "INSTANTLY_API_KEY": "your-v2-api-key" }
    }
  }
}

Obtén una clave de API v2 desde el panel de Instantly en Configuración → Integraciones → API. Requiere Node 20+.

El modelo de seguridad

Las herramientas se agrupan en tres niveles, controlados por variables de entorno. Un nivel deshabilitado no se registra con el servidor MCP en absoluto — un modelo que hable con este servidor literalmente no puede ver ni intentar una herramienta que no tiene permitido usar; esto no es una verificación de permisos en tiempo de ejecución que un prompt inteligente pudiera eludir.

El nivel peligroso requiere ambas banderas a propósito: activar escrituras rutinarias (subir leads, bloquear una dirección) nunca habilita silenciosamente también la activación de campañas, el envío o la eliminación. Esas cuatro herramientas además llevan la anotación destructiveHint: true de MCP — una pista que un cliente compatible puede actuar (por ejemplo, pidiendo confirmación al usuario) incluso cuando el nivel está habilitado. Es un comportamiento impuesto por el cliente, no una garantía que este servidor haga: un cliente que ignore la pista llamará a la herramienta sin ningún paso de confirmación adicional.

Herramientas

Lectura (siempre registradas)

• list_campaigns — lista todas las campañas, incluidos los borradores, con el estado numérico decodificado.

• list_accounts — lista los buzones de envío conectados con puntuación de calentamiento, estado y límite diario.

• campaign_state — verifica de forma cruzada el estado de una campaña en tres endpoints independientes e informa dónde discrepan, en lugar de elegir un ganador. La lectura de la lista de leads está limitada a una página (una página, límite 100); una página completa se informa claramente como limitada por página, nunca como una discrepancia de Instantly.

• list_leads — lista los leads de una campaña, filtrados por el parámetro singular campaign, con una advertencia si el propio campo campaign de algún lead devuelto discrepa. Lee una página (límite predeterminado 100); pageLimited en el resultado te indica cuándo puede haber más leads más allá de ella.

• find_lead — encuentra un lead por correo electrónico mediante el parámetro search; la segunda opinión correcta cuando list_leads parece incorrecto. search es difuso, por lo que la fila se devuelve solo cuando su propia dirección coincide con la solicitada — una coincidencia cercana se informa como null, nunca como el lead.

• list_replies — lista las respuestas recibidas con el hilo citado/firma eliminados y el estado de interés decodificado.

Escritura (INSTANTLY_MCP_WRITE=1)

• add_leads — sube leads a una campaña, verificado por diff (no por recuento) en dos rutas de lectura independientes. En una campaña con más de 100 leads, la lectura de verificación también está limitada por página — los campos pageLimited y note del resultado lo indican.

• blocklist_address — bloquea una dirección de correo electrónico completa; rechaza estructuralmente dominios desnudos.

• update_lead — modifica los campos de un lead.

• create_campaign — crea una campaña como borrador (nunca envía); valida la enumeración de zona horaria antes de cualquier llamada de red.

• create_webhook — crea una suscripción de webhook; valida la enumeración de tipo de evento antes de cualquier llamada de red.

Peligroso (INSTANTLY_MCP_WRITE=1 y INSTANTLY_MCP_ALLOW_DANGEROUS=1)

• set_campaign_status — activa o pausa una campaña; activar comienza a enviar correo real inmediatamente.

• send_reply — envía una respuesta real e irrevocable a un lead. El texto plano se escapa en HTML y se divide en líneas para el cuerpo html en lugar de pegarse crudo; pasa html tú mismo para anularlo.

• delete_lead — elimina permanentemente un lead.

• delete_campaign — elimina permanentemente una campaña y su historial.

Limitaciones conocidas

list_replies elimina el hilo original citado y la firma de cada respuesta (src/reply-text.ts). Es deliberadamente conservador: en entradas ambiguas deja la cita en lugar de arriesgarse a eliminar texto real. Por lo tanto, cada borde restante a continuación falla en la dirección SEGURA — un hilo citado sobrevive en el texto devuelto, lo cual es ruido, en lugar de que se elimine una oración, lo cual sería pérdida de datos:

• Una atribución que nombra solo un día de la semana, p. ej. On Tuesday ... wrote:, no lleva ninguna de las señales de fecha/hora que el eliminador requiere, por lo que no se elimina.

• Una atribución que nombra un remitente en minúsculas sin dirección, p. ej. ... at 8:22 AM, john wrote:, falla la verificación de forma del remitente (un remitente real se lee como una dirección, un nombre capitalizado o un pronombre) y no se elimina.

• Un cuerpo que es completamente una firma (-- en la primera línea no en blanco, sin nada antes) se devuelve completo, incluido el delimitador, en lugar de vaciarse.

Dos recortes excesivos detectados durante el desarrollo sí eliminaron texto real de prospectos: un cuerpo que comenzaba con -- se vació por completo, y un texto con la forma On May 5 reasons you wrote: ... se malinterpretó como un marcador de hilo citado y se recortó. Ambos se corrigieron antes de la primera versión y están cubiertos por la suite offline (test/reply-text.test.ts, "Fix round 4").

Todavía no existe ninguna herramienta que devuelva el body.text sin procesar y sin recortar de una respuesta. Si una respuesta de list_replies parece sospechosamente corta, compruébala en el panel de Instantly antes de concluir que el prospecto dijo menos de lo que realmente dijo.

Trabajo previo

Un paquete existente, instantly-mcp de bcharleson, cubre un terreno similar y se publicó por última vez el 2025-06-17. A fecha de 2026-08-21, su etiqueta latest de npm apunta a 1.0.5, mientras que su etiqueta next lleva 3.0.5-1 — por lo que un simple npx instantly-mcp instala una compilación mucho más antigua que el código publicado más reciente del propio paquete (las dist tags pueden cambiar después de que esto se escribiera; vuelve a consultar npm view instantly-mcp dist-tags para conocer el estado actual). Esto se afirma de forma objetiva, no como una crítica: instantly-ai-mcp es un proyecto independiente y no afiliado, con un enfoque distinto (la tabla de gotchas y su autoverificación), más que un fork o un reemplazo.

Pruebas

La suite de fixtures (npm test) se ejecuta completamente sin conexión contra clientes simulados y no necesita ninguna clave de API. Una suite de integración en vivo independiente, activada mediante INSTANTLY_LIVE_TEST=1 (y una INSTANTLY_API_KEY real), pone a prueba la API real — pero solo crea, lee y elimina su propia campaña de borrador desechable (llamada zz-instantly-ai-mcp-throwaway-<timestamp>), nunca una campaña o un prospecto existente, y nunca activa ni envía nada. Se omite automáticamente cuando la variable o la clave no están presentes, lo que siempre ocurre en CI.

Licencia

MIT