Instantly

Gestiona campañas de correo electrónico y leads utilizando la API v2 de Instantly.ai.

Documentación

Instantly MCP Server (Python)

Un servidor ligero y robusto del Model Context Protocol (MCP) para la API de Instantly.ai V2, construido con FastMCP.

Características

38 herramientas en 6 categorías (accounts, campaigns, leads, emails, analytics, background_jobs)
Soporte de transporte dual: HTTP (despliegue remoto) + stdio (local)
Carga diferida: Reduce la ventana de contexto cargando solo categorías de herramientas específicas
Soporte multi-tenant: Claves API por solicitud para despliegues HTTP
Manejo integral de errores: Mensajes de error detallados y accionables
Límite de tasa: Seguimiento automático desde los encabezados de respuesta de la API
Tiempos de espera dinámicos: Tiempos de espera extendidos para operaciones de búsqueda y masivas

Inicio Rápido

Instalación

# Clone or navigate to the repository
cd instantly-mcp-python

# Install with pip
pip install -e .

# Or install dependencies directly
pip install fastmcp httpx pydantic python-dotenv

Configuración

Establece tu clave de API de Instantly:

export INSTANTLY_API_KEY="your-api-key-here"

O crea un archivo .env:

INSTANTLY_API_KEY=your-api-key-here

Ejecutando el Servidor

Modo HTTP (Recomendado para Despliegue Remoto)

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py --transport http --port 8000

# Using Python directly
python -m instantly_mcp.server --transport http --port 8000

# Or with uvicorn for production
uvicorn instantly_mcp.server:mcp.app --host 0.0.0.0 --port 8000

Modo stdio (Desarrollo Local)

# Using FastMCP CLI
fastmcp run src/instantly_mcp/server.py

# Using Python directly
python -m instantly_mcp.server

Categorías de Herramientas

Accounts (6 herramientas)

Herramienta	Descripción
`list_accounts`	Listar cuentas de correo con filtrado
`get_account`	Obtener detalles de la cuenta y estado de calentamiento
`create_account`	Crear cuenta con credenciales IMAP/SMTP
`update_account`	Actualizar configuración de la cuenta
`manage_account_state`	Pausar, reanudar, control de calentamiento, probar vitales
`delete_account`	⚠️ Eliminar cuenta permanentemente

Campaigns (8 herramientas)

Herramienta	Descripción
`create_campaign`	Crear campaña de correo electrónico (proceso de dos pasos)
`list_campaigns`	Listar campañas con paginación
`get_campaign`	Obtener detalles de la campaña y secuencias
`update_campaign`	Actualizar configuración de la campaña
`activate_campaign`	Iniciar envío de la campaña
`pause_campaign`	Detener envío de la campaña
`delete_campaign`	⚠️ Eliminar campaña permanentemente
`search_campaigns_by_contact`	Encontrar campañas en las que un contacto está inscrito

Leads (12 herramientas)

Herramienta	Descripción
`list_leads`	Listar leads con filtrado
`get_lead`	Obtener detalles del lead
`create_lead`	Crear un lead individual
`update_lead`	Actualizar lead (⚠️ custom_variables reemplaza todo)
`list_lead_lists`	Listar listas de leads
`create_lead_list`	Crear lista de leads
`update_lead_list`	Actualizar lista de leads
`get_verification_stats_for_lead_list`	Obtener estadísticas de verificación de correo electrónico
`add_leads_to_campaign_or_list_bulk`	Agregar en masa hasta 1,000 leads
`delete_lead`	⚠️ Eliminar lead permanentemente
`delete_lead_list`	⚠️ Eliminar lista de leads permanentemente
`move_leads_to_campaign_or_list`	Mover/copiar leads entre campañas/listas

Emails (6 herramientas)

Herramienta	Descripción
`list_emails`	Listar correos electrónicos con filtrado
`get_email`	Obtener detalles del correo electrónico
`reply_to_email`	🚨 Enviar respuesta de correo electrónico real
`count_unread_emails`	Contar correos electrónicos no leídos en la bandeja de entrada
`verify_email`	Verificar la entregabilidad del correo electrónico
`mark_thread_as_read`	Marcar hilo de correo electrónico como leído

Analytics (3 herramientas)

Herramienta	Descripción
`get_campaign_analytics`	Métricas de campaña (aperturas, clics, respuestas)
`get_daily_campaign_analytics`	Rendimiento día a día
`get_warmup_analytics`	Métricas de calentamiento de cuenta

Background Jobs (2 herramientas)

Herramienta	Descripción
`list_background_jobs`	Listar trabajos en segundo plano asíncronos con paginación
`get_background_job`	Obtener detalles de un trabajo en segundo plano específico

Carga Diferida (Optimización de la Ventana de Contexto)

Reduce el uso de la ventana de contexto cargando solo las categorías que necesites:

# Load only accounts and campaigns (14 tools instead of 38)
export TOOL_CATEGORIES="accounts,campaigns"

# Load only leads and analytics
export TOOL_CATEGORIES="leads,analytics"

Categorías válidas: accounts, campaigns, leads, emails, analytics, background_jobs

Métodos de Autenticación

El servidor admite múltiples métodos de autenticación para mayor flexibilidad:

1. Autenticación basada en URL

Incluye tu clave de API directamente en la ruta de la URL:

https://your-server.com/mcp/YOUR_API_KEY

2. Autenticación por Encabezado

URL: https://your-server.com/mcp
Header: Authorization: YOUR_API_KEY

Nota: el prefijo del token Bearer es opcional

3. Encabezado Personalizado

URL: https://your-server.com/mcp
Header: x-instantly-api-key: YOUR_API_KEY

4. Variable de Entorno

export INSTANTLY_API_KEY="your-api-key-here"

Configuración del Cliente MCP

Claude Desktop

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json:

Modo stdio (Local)

{
  "mcpServers": {
    "instantly": {
      "command": "python",
      "args": ["-m", "instantly_mcp.server"],
      "env": {
        "INSTANTLY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Modo HTTP con Autenticación por URL (Recomendado)

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

Modo HTTP con Autenticación por Encabezado

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "your-api-key-here"
      }
    }
  }
}

Cursor IDE

Agrega a ~/.cursor/mcp.json:

Con Autenticación por URL

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp/YOUR_API_KEY"
    }
  }
}

Con Autenticación por Encabezado

{
  "mcpServers": {
    "instantly": {
      "url": "https://your-server.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "x-instantly-api-key": "your-api-key-here"
      }
    }
  }
}

Despliegue en la Plataforma de Aplicaciones de DigitalOcean

Especificación de la Aplicación

name: instantly-mcp
services:
  - name: instantly-mcp
    source:
      git:
        branch: main
        repo_clone_url: https://github.com/your-username/instantly-mcp-python.git
    build_command: pip install -e .
    run_command: python -m instantly_mcp.server --transport http --port 8080
    http_port: 8080
    instance_size_slug: basic-xxs
    instance_count: 1
    envs:
      - key: INSTANTLY_API_KEY
        scope: RUN_TIME
        type: SECRET
      - key: PORT
        scope: RUN_TIME
        value: "8080"

Dockerfile (Alternativa)

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml .
COPY src/ src/

RUN pip install -e .

EXPOSE 8000

CMD ["python", "-m", "instantly_mcp.server", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]

Modo HTTP Multi-Tenant

Para despliegues que atienden a múltiples usuarios, el servidor admite claves de API por solicitud:

# Start server without default API key
python -m instantly_mcp.server --transport http --port 8000

# Clients provide API key via header
curl -X POST http://localhost:8000/mcp \
  -H "x-instantly-api-key: user-specific-api-key" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Manejo de Errores

El servidor proporciona mensajes de error detallados y accionables:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Instantly API key is required. Provide via:\n  - INSTANTLY_API_KEY environment variable\n  - api_key parameter\n  - x-instantly-api-key header (HTTP mode)"
  }
}

Límite de Tasa

El servidor rastrea automáticamente los límites de tasa desde los encabezados de respuesta de la API:

# Access via get_server_info tool
{
  "rate_limit": {
    "remaining": 95,
    "limit": 100,
    "reset_at": "2024-01-15T12:00:00"
  }
}

Estructura del Proyecto

instantly-mcp-python/
├── src/
│   └── instantly_mcp/
│       ├── __init__.py          # Package exports
│       ├── server.py            # FastMCP server (~180 lines)
│       ├── client.py            # API client (~200 lines)
│       ├── models/              # Pydantic models
│       │   ├── __init__.py
│       │   ├── common.py        # Pagination
│       │   ├── accounts.py      # Account models
│       │   ├── campaigns.py     # Campaign models
│       │   ├── leads.py         # Lead models
│       │   ├── emails.py        # Email models
│       │   └── analytics.py     # Analytics models
│       └── tools/               # Tool implementations
│           ├── __init__.py      # Lazy loading logic
│           ├── accounts.py      # 6 account tools
│           ├── campaigns.py     # 8 campaign tools
│           ├── leads.py         # 12 lead tools
│           ├── emails.py        # 6 email tools
│           ├── analytics.py     # 3 analytics tools
│           └── background_jobs.py # 2 background job tools
├── pyproject.toml               # Dependencies
├── env.example                  # Environment template
└── README.md                    # This file

Comparación con la Versión de TypeScript

Aspecto	TypeScript	Python FastMCP
Líneas de Código	~5,000+	~1,500
Registro de Herramientas	Manejadores manuales	decorador `@mcp.tool`
Validación de Entrada	Esquemas Zod	Pydantic (automático)
Mensajes de Error	Manuales	Automáticos desde Pydantic
Servidor HTTP	Transporte personalizado	Integrado
Ventana de Contexto	Esquemas más grandes	Más pequeña y limpia

Referencia de la API

Para documentación detallada de la API, consulta: Instantly V2 API Docs

Licencia

Licencia MIT

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o un PR.