Mailchimp MCP

Servidor MCP do Mailchimp

O servidor mais completo de Model Context Protocol (MCP) para a Mailchimp Marketing API: 227 ferramentas para consultar e gerenciar sua conta Mailchimp a partir de qualquer cliente compatível com MCP. Ele cobre toda a superfície de campanhas, públicos, membros, segmentos, automações e relatórios, e-commerce completo (leitura e escrita), landing pages, Gerenciador de Arquivos, pesquisas, formulários de inscrição e domínios verificados, além de suporte a múltiplas contas e proteções de segurança em tempo de execução (modos somente leitura, simulação e auditoria, com metadados de risco por ferramenta).

Usa a Mailchimp Marketing API via requests. Não é baseado no cliente oficial mailchimp-marketing-python. Encontrei muitos problemas com ele, então optei por chamadas HTTP diretas.

Início rápido

uvx mailchimp-mcp   # no install required; just needs MAILCHIMP_API_KEY

Adicione-o ao seu cliente MCP (Claude Desktop, Cursor, Cline, …):

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Dica: comece com MAILCHIMP_READ_ONLY=true para explorar com segurança e depois desative quando estiver pronto para escrever. Consulte Configuração para todas as opções.

Docker

Uma imagem pré-construída é publicada no GitHub Container Registry a cada versão:

docker run --rm -i -e MAILCHIMP_API_KEY=your-key-us8 ghcr.io/damientilman/mailchimp-mcp-server:latest

Ou aponte seu cliente MCP para ela:

{
  "mcpServers": {
    "mailchimp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "MAILCHIMP_API_KEY", "-e", "MAILCHIMP_READ_ONLY", "ghcr.io/damientilman/mailchimp-mcp-server:latest"],
      "env": {
        "MAILCHIMP_API_KEY": "your-key-us8",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Recursos

Leitura

• Campanhas - Listar, pesquisar e inspecionar detalhes de campanhas
• Relatórios - Taxas de abertura/cliques, rejeições, cliques por link, desempenho por domínio, detalhes de cancelamentos de inscrição
• Atividade de e-mail - Rastreamento de aberturas/cliques por destinatário, histórico de atividade de membros
• Públicos - Navegar por públicos, membros, segmentos, tags e histórico de crescimento
• Campos de mesclagem - Listar campos personalizados de um público
• Categorias e grupos de interesse - Navegar por categorias e opções de interesse
• Webhooks - Listar webhooks configurados
• Segmentos - Obter detalhes de segmentos, condições e listas de membros
• Automações - Listar fluxos de trabalho, inspecionar e-mails em um fluxo de trabalho, visualizar filas
• Modelos - Navegar por modelos e extrair conteúdo HTML
• Landing pages - Listar e inspecionar landing pages
• Gerenciador de Arquivos - Navegar por imagens, arquivos e pastas armazenados
• Pesquisas - Listar e inspecionar pesquisas de um público
• Formulários de inscrição - Inspecionar formulários de inscrição de um público
• E-commerce - Lojas, pedidos, produtos, clientes (requer integração de e-commerce)
• Pastas de campanhas - Navegar pela organização de pastas
• Operações em lote - Monitorar status de operações em massa

Escrita

• Membros - Adicionar, atualizar, cancelar inscrição, excluir e marcar contatos
• Públicos - Assinar membros em lote, atualizar configurações do público
• Campanhas - Criar rascunhos, definir conteúdo HTML, agendar, desagendar, duplicar, excluir, enviar, enviar teste, cancelar
• Segmentos/Tags - Criar, atualizar, excluir, adicionar/remover membros, condições dinâmicas
• Campos de mesclagem - Criar, atualizar, excluir campos personalizados
• Categorias de interesse - Criar e excluir categorias e interesses
• Webhooks - Criar e excluir webhooks
• Modelos - Criar, atualizar e excluir modelos de e-mail
• Gerenciador de Arquivos - Enviar (base64) e excluir imagens e arquivos
• Pesquisas - Publicar e despublicar pesquisas de público
• Formulários de inscrição - Personalizar cabeçalho, conteúdos e estilos
• Automações - Pausar e iniciar fluxos de trabalho de automação
• E-commerce - Ciclo de vida do carrinho, regras promocionais e códigos promocionais para fluxos de desconto
• Lote - Executar operações de API em massa em uma única solicitação

Segurança em tempo de execução

• Metadados de risco - Classificação por ferramenta de leitura / escrita / destrutiva via anotações MCP e describe_tools
• Log de auditoria - Eventos de auditoria JSON estruturados opcionais por despacho (MAILCHIMP_AUDIT_LOG)
• Validação de argumentos - Limites de paginação e verificações de IDs obrigatórios antes de cada solicitação

Pré-requisitos

• Python 3.10+
• Uma chave de API do Mailchimp

Instalação

Usando uvx (recomendado)

Nenhuma instalação necessária — execute diretamente:

uvx mailchimp-mcp

Usando pip

pip install mailchimp-mcp

Depois execute:

mailchimp-mcp

A partir do código-fonte

git clone https://github.com/damientilman/mailchimp-mcp-server.git
cd mailchimp-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuração

O datacenter (us8, us21, etc.) é extraído automaticamente de cada chave.

Modos de segurança

Modo somente leitura — Quando MAILCHIMP_READ_ONLY=true, todas as ferramentas de escrita (criar, atualizar, excluir, agendar, etc.) são bloqueadas e retornam um erro. As ferramentas de leitura funcionam normalmente. Este é o padrão recomendado para configurações compartilhadas ou exploratórias onde você só precisa de relatórios e análises.

Modo de simulação — Quando MAILCHIMP_DRY_RUN=true, as ferramentas de escrita retornam uma prévia da ação que executariam (nome da ferramenta, recurso de destino, parâmetros e nível de risco) sem fazer nenhuma chamada de API. Útil para testar prompts antes de entrar em produção.

Segurança em tempo de execução

O servidor foi projetado para defesa em profundidade junto a um gateway MCP externo: ele possui a semântica (quais ferramentas são leituras, escritas reversíveis ou irreversíveis) e as expõe como sinais legíveis por máquina que um gateway pode aplicar, em vez de fazer o gateway adivinhar quais chamadas são perigosas.

Metadados de risco — Cada ferramenta é classificada como read, write ou destructive (perda de dados irreversível ou envio irreversível). Isso aparece de duas formas:

• Anotações de ferramentas MCP — readOnlyHint, destructiveHint e idempotentHint trafegam pelo tools/list padrão, então qualquer cliente ou gateway compatível os lê diretamente.
• describe_tools — uma ferramenta de leitura que retorna {name, risk, read_only, destructive, idempotent} para cada ferramenta, além de contagens por nível, para gateways que preferem uma chamada de ferramenta.

Log de auditoria estruturado — Com MAILCHIMP_AUDIT_LOG=true, cada despacho emite um evento JSON para stderr com a ferramenta, seu nível de risco, o sinalizador destructive, a conta de destino, o resultado (executed / blocked_read_only / dry_run) e os argumentos inspecionados. Valores volumosos ou sensíveis (ex.: file_data base64) são ocultados e os corpos de resposta nunca são registrados, então o fluxo é um destino de auditoria seguro para monitoramento central.

Validação de contrato de argumentos — Todas as escritas passam por um único ponto de verificação _guard_write, e cada solicitação é validada antes do despacho (paginação count limitada a 1–1000, IDs de caminho ausentes rejeitados), para que chamadas malformadas falhem rapidamente e de forma consistente, em vez de atingirem a API.

Perfis de ferramentas

Expor todas as 227 ferramentas envia uma grande lista de ferramentas ao modelo a cada turno (~63 mil tokens). Se você precisar apenas de parte da superfície, carregue um subconjunto com uma linha:

"env": { "MAILCHIMP_API_KEY": "your-key-us8", "MAILCHIMP_TOOLS": "read" }

MAILCHIMP_TOOLS aceita uma mistura separada por vírgulas de níveis de risco (read, write, destructive) e/ou nomes exatos de ferramentas; uma ferramenta é mantida se qualquer um corresponder. Não definido (ou all) expõe tudo.

• read — apenas relatórios e análises (~115 ferramentas, ~29 mil tokens). Um padrão seguro e leve para exploração.
• read,write — tudo, exceto ferramentas irreversíveis.
• list_campaigns,get_campaign_report,send_campaign — um conjunto mínimo selecionado manualmente.

As descrições das ferramentas também são reduzidas de textos repetidos antes de chegarem ao modelo, então até o conjunto completo é mais enxuto que as docstrings brutas. Use describe_tools para ver o nível de risco de cada ferramenta.

Multi-contas

Por padrão, o servidor usa o único MAILCHIMP_API_KEY, exposto como a conta default. Para gerenciar várias contas Mailchimp a partir de um servidor, adicione variáveis MAILCHIMP_API_KEY_<NAME> — o sufixo se torna o nome da conta em minúsculas (ex.: MAILCHIMP_API_KEY_MARKETING → marketing).

Cada ferramenta então aceita um argumento opcional account, ex.: list_audiences(account="marketing"). A seleção é por chamada e sem estado — não há "conta atual" para alternar, então uma escrita sempre nomeia seu destino. Omitir account usa default. Chame list_accounts para ver os nomes configurados e o estado de seus sinalizadores de segurança, e cada conta pode ter seus próprios sinalizadores MAILCHIMP_READ_ONLY_<NAME> / MAILCHIMP_DRY_RUN_<NAME> (para que uma conta protegida contra escrita e uma gravável possam coexistir). Um account desconhecido retorna um erro listando os nomes configurados.

Configurações de chave única não são afetadas: com apenas MAILCHIMP_API_KEY definido, nada muda.

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-default-key-us8",
        "MAILCHIMP_API_KEY_MARKETING": "another-key-us5",
        "MAILCHIMP_READ_ONLY_MARKETING": "true"
      }
    }
  }
}

Configuração do cliente MCP

A maioria dos clientes MCP aceita um bloco de configuração JSON descrevendo como iniciar o servidor. Configure o seu para invocar uvx mailchimp-mcp (ou mailchimp-mcp se instalado via pip) com MAILCHIMP_API_KEY exportado no ambiente.

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "mailchimp-mcp",
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "mailchimp": {
      "command": "uvx",
      "args": ["mailchimp-mcp"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_READ_ONLY": "true"
      }
    }
  }
}

Clientes baseados em CLI

Se o seu cliente MCP fornece uma CLI para registrar servidores, a invocação equivalente é:

mcp-cli add mailchimp \
  -e MAILCHIMP_API_KEY=your-api-key-here \
  -- uvx mailchimp-mcp

Substitua mcp-cli pelo nome do binário do seu cliente. Para o modo somente leitura, adicione -e MAILCHIMP_READ_ONLY=true ao comando.

Ferramentas disponíveis

Conta

Campanhas (leitura)

Relatórios de campanhas

Campanhas (escrita)

Públicos (leitura)

Membros (leitura)

Membros (escrita)

Públicos (escrita)

Segmentos e Tags

Campos de Mesclagem

Categorias de Interesse e Grupos

Webhooks

Automações e Jornadas do Cliente

O Mailchimp não expõe uma API pública de leitura para Jornadas do Cliente (apenas o endpoint de gatilho acima). As ferramentas search_automation_campaigns, get_member_journey_events e get_automation_summary fornecem as soluções alternativas recomendadas — elas exibem todas as campanhas emitidas por automações ou jornadas, mesmo que o gráfico da jornada em si permaneça privado.

Modelos

Páginas de Destino

Gerenciador de Arquivos

Pesquisas

Formulários de Inscrição

E-commerce

Carrinhos de E-commerce

Regras e Códigos Promocionais de E-commerce

Operações em Lote

Domínios Verificados

Sites Conectados e Conta

Pastas

Extras de Campanha (checklist, colaboração, RSS)

Insights de Público e Entregabilidade

Membros (conformidade e avançado)

E-mails de Automação (controle de e-mail único)

Relatórios (extras)

E-commerce (escrita)

Exemplos de Prompts

Depois de conectado, você pode pedir ao seu cliente MCP para executar solicitações como:

• "Mostre-me todas as minhas campanhas enviadas nos últimos 3 meses"
• "Qual foi a taxa de abertura e a taxa de cliques da minha última newsletter?"
• "Quantos assinantes ganhei este ano?"
• "Quais links tiveram mais cliques na campanha X?"
• "Buscar o assinante john@example.com"
• "Adicionar a tag 'VIP' a todos os membros que abriram minha última campanha"
• "Criar uma campanha rascunho para meu público principal com o assunto 'Atualização de Março'"
• "Criar uma campanha segmentada apenas para meu segmento VIP"
• "Enviar um e-mail de teste da minha campanha rascunho para test@example.com"
• "Listar todos os campos de mesclagem do meu público principal"
• "Criar um campo de mesclagem suspenso chamado 'Setor' com as opções Tecnologia, Finanças, Saúde"
• "Criar um segmento dinâmico de membros onde FNAME é João"
• "Assinar 50 membros em lote a partir destes dados CSV"
• "Configurar um webhook para notificar meu aplicativo quando novos assinantes entrarem"
• "Cancelar a inscrição de user@example.com da minha lista"
• "Mostre-me o detalhamento de desempenho por domínio da minha última campanha"
• "Onde no mundo as pessoas abriram minha newsletter? Mostre-me o detalhamento geográfico."
• "Criar uma campanha de teste A/B com duas linhas de assunto e escolher o vencedor por aberturas após 24 horas"
• "Que conselhos o Mailchimp tem para melhorar minha última campanha?"
• "Pausar minha automação de boas-vindas"
• "Listar todos os pedidos da minha loja Shopify neste mês"

Receitas de fluxo de trabalho

Solicitações de várias etapas que encadeiam ferramentas de ponta a ponta:

• Revisão de desempenho semanal — "Resuma minha última semana: liste as campanhas enviadas desde segunda-feira, puxe cada relatório e classifique-as por taxa de cliques com uma conclusão para cada uma." Encadeia search_campaigns → get_campaign_report → get_campaign_advice.
• Auditoria de entregabilidade — "Verifique minha saúde de envio: meus domínios estão verificados, há alguma reclamação de spam em campanhas recentes e como foi o desempenho da última por domínio do destinatário?" Encadeia list_verified_domains → get_campaign_abuse_reports → get_domain_performance.
• Reengajamento — "Encontre todos que não abriram minha última newsletter e reenvie-a com uma nova linha de assunto." Encadeia get_campaign_report → resend_to_non_openers.
• Envio seguro — "Faça uma simulação de campanha para meu segmento VIP, mostre-me a lista de verificação de envio e depois envie quando eu confirmar." Com MAILCHIMP_DRY_RUN=true, pré-visualizações via create_campaign → get_campaign_send_checklist → send_campaign.
• Agências (multi-conta) — "Para as contas acme e globex, liste a melhor campanha deste mês por taxa de abertura." Passa account="acme" / account="globex" por chamada. Veja Multi-conta.

Contribuindo

Contribuições são bem-vindas. Veja CONTRIBUTING.md para configuração de desenvolvimento, instruções de teste e diretrizes de pull request.

Segurança

Se você encontrar uma vulnerabilidade de segurança, siga o processo de divulgação responsável descrito em SECURITY.md.

Changelog

Veja CHANGELOG.md para o histórico completo de versões.

Autor

Construído por Damien Tilman — damien@tilman.marketing

Licença

MIT — veja LICENSE para detalhes.