Instantly

Gerencie campanhas de e-mail e leads usando a API v2 do Instantly.ai.

GitHub

Experimente este MCPPatrocinado

Documentação

Instantly MCP Server (Python)

Um servidor leve e robusto do Model Context Protocol (MCP) para a Instantly.ai V2 API, construído com FastMCP.

Recursos

38 ferramentas em 6 categorias (contas, campanhas, leads, e-mails, análises, trabalhos em segundo plano)
Suporte a transporte duplo: HTTP (implantação remota) + stdio (local)
Carregamento preguiçoso: Reduza a janela de contexto carregando apenas categorias específicas de ferramentas
Suporte multi-tenant: Chaves de API por solicitação para implantações HTTP
Tratamento abrangente de erros: Mensagens de erro detalhadas e acionáveis
Limitação de taxa: Rastreamento automático a partir dos cabeçalhos de resposta da API
Tempos limite dinâmicos: Tempos limite estendidos para operações de busca e em massa

Início Rápido

Instalação

# 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

Configuração

Defina sua chave de API do Instantly:

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

Ou crie um arquivo .env:

INSTANTLY_API_KEY=your-api-key-here

Executando o Servidor

Modo HTTP (Recomendado para Implantação Remota)

# 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 (Desenvolvimento Local)

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

# Using Python directly
python -m instantly_mcp.server

Categorias de Ferramentas

Contas (6 ferramentas)

Ferramenta	Descrição
`list_accounts`	Listar contas de e-mail com filtragem
`get_account`	Obter detalhes da conta e status de aquecimento
`create_account`	Criar conta com credenciais IMAP/SMTP
`update_account`	Atualizar configurações da conta
`manage_account_state`	Pausar, retomar, controle de aquecimento, testar vitals
`delete_account`	⚠️ Excluir conta permanentemente

Campanhas (8 ferramentas)

Ferramenta	Descrição
`create_campaign`	Criar campanha de e-mail (processo em duas etapas)
`list_campaigns`	Listar campanhas com paginação
`get_campaign`	Obter detalhes da campanha e sequências
`update_campaign`	Atualizar configurações da campanha
`activate_campaign`	Iniciar envio da campanha
`pause_campaign`	Parar envio da campanha
`delete_campaign`	⚠️ Excluir campanha permanentemente
`search_campaigns_by_contact`	Encontrar campanhas em que um contato está inscrito

Leads (12 ferramentas)

Ferramenta	Descrição
`list_leads`	Listar leads com filtragem
`get_lead`	Obter detalhes do lead
`create_lead`	Criar lead individual
`update_lead`	Atualizar lead (⚠️ custom_variables substitui tudo)
`list_lead_lists`	Listar listas de leads
`create_lead_list`	Criar lista de leads
`update_lead_list`	Atualizar lista de leads
`get_verification_stats_for_lead_list`	Obter estatísticas de verificação de e-mail
`add_leads_to_campaign_or_list_bulk`	Adicionar em massa até 1.000 leads
`delete_lead`	⚠️ Excluir lead permanentemente
`delete_lead_list`	⚠️ Excluir lista de leads permanentemente
`move_leads_to_campaign_or_list`	Mover/copiar leads entre campanhas/listas

E-mails (6 ferramentas)

Ferramenta	Descrição
`list_emails`	Listar e-mails com filtragem
`get_email`	Obter detalhes do e-mail
`reply_to_email`	🚨 Enviar resposta de e-mail real
`count_unread_emails`	Contar e-mails não lidos na caixa de entrada
`verify_email`	Verificar entregabilidade do e-mail
`mark_thread_as_read`	Marcar thread de e-mail como lida

Análises (3 ferramentas)

Ferramenta	Descrição
`get_campaign_analytics`	Métricas da campanha (aberturas, cliques, respostas)
`get_daily_campaign_analytics`	Desempenho dia a dia
`get_warmup_analytics`	Métricas de aquecimento da conta

Trabalhos em Segundo Plano (2 ferramentas)

Ferramenta	Descrição
`list_background_jobs`	Listar trabalhos em segundo plano assíncronos com paginação
`get_background_job`	Obter detalhes de um trabalho em segundo plano específico

Carregamento Preguiçoso (Otimização da Janela de Contexto)

Reduza o uso da janela de contexto carregando apenas as categorias que você precisa:

# 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"

Categorias válidas: accounts, campaigns, leads, emails, analytics, background_jobs

Métodos de Autenticação

O servidor suporta vários métodos de autenticação para flexibilidade:

1. Autenticação Baseada em URL

Inclua sua chave de API diretamente no caminho da URL:

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

2. Autenticação por Cabeçalho

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

Nota: O prefixo do token Bearer é opcional

3. Cabeçalho Personalizado

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

4. Variável de Ambiente

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

Configuração do Cliente MCP

Claude Desktop

Adicione ao ~/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 com Autenticação por URL (Recomendado)

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

Modo HTTP com Autenticação por Cabeçalho

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

Cursor IDE

Adicione ao ~/.cursor/mcp.json:

Com Autenticação por URL

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

Com Autenticação por Cabeçalho

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

Implantação na Plataforma de Aplicativos DigitalOcean

Especificação do Aplicativo

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 implantações que atendem vários usuários, o servidor suporta chaves de API por solicitação:

# 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"}'

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas e acionáveis:

{
  "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)"
  }
}

Limitação de Taxa

O servidor rastreia automaticamente os limites de taxa a partir dos cabeçalhos de resposta da API:

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

Estrutura do Projeto

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

Comparação com a Versão TypeScript

Aspecto	TypeScript	Python FastMCP
Linhas de Código	~5.000+	~1.500
Registro de Ferramentas	Manipuladores manuais	Decorador `@mcp.tool`
Validação de Entrada	Esquemas Zod	Pydantic (automático)
Mensagens de Erro	Manual	Automático do Pydantic
Servidor HTTP	Transporte personalizado	Integrado
Janela de Contexto	Esquemas maiores	Menor, mais limpo

Referência da API

Para documentação detalhada da API, consulte: Instantly V2 API Docs

Licença

Licença MIT

Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou PR.