ActiveCampaign MCP Server
Um servidor MCP (Model Context Protocol) para integração com a API do ActiveCampaign, permitindo consultas e análises de contatos e eventos de tracking através de ferramentas AI-friendly.
✨ Funcionalidades
🔍 Gerenciamento de Contatos
- Busca por email: Encontre contatos usando endereço de email
- Busca por ID: Recupere contatos específicos pelo ID
- Pesquisa avançada: Busque contatos com filtros e paginação
- Dados enriquecidos: Inclui campos customizados, tags e listas
📊 Tracking e Analytics
- Logs de eventos: Acesse histórico completo de eventos por contato
- Filtros avançados: Filtre por tipo de evento, data e outros critérios
- Busca por email: Obtenha tracking logs usando apenas o email do contato
- Dados estruturados: Eventos formatados com timestamps, descrições e metadata
🛠️ Tipos de Eventos Suportados
- Email:
open, click, sent, bounce, reply, forward - Gerenciamento:
subscribe, unsubscribe, update - Vendas:
deal_add, deal_update, deal_delete - Produtividade:
note_add, task_add - Automação:
automation_start, automation_complete
🚀 Instalação
Pré-requisitos
- Node.js 18 ou superior
- NPM ou PNPM
- Conta no ActiveCampaign com acesso à API
Passos de Instalação
- Clone o repositório
git clone https://github.com/mmarqueti/activecampaign-mcp-server.git
cd activecampaign-mcp-server
- Instale as dependências
# Com npm
npm install
# Com pnpm
pnpm install
- Configure as variáveis de ambiente
Edite o arquivo .env com suas credenciais:
ACTIVECAMPAIGN_API_URL=https://seuaccount.api-us1.com
ACTIVECAMPAIGN_API_KEY=sua-api-key-aqui
- Compile o projeto
# Com npm
npm run build
# Com pnpm
pnpm build
⚙️ Configuração
Obtendo Credenciais do ActiveCampaign
- Acesse sua conta do ActiveCampaign
- Vá para Settings > Developer
- Copie sua API URL e API Key
- Cole as credenciais no arquivo
.env
Variáveis de Ambiente
| Variável | Descrição | Exemplo |
|---|
ACTIVECAMPAIGN_API_URL | URL base da API | https://seuaccount.api-us1.com |
ACTIVECAMPAIGN_API_KEY | Chave da API | your-api-key-here |
🔧 Uso
Iniciando o Servidor
# Modo desenvolvimento
npm run dev
# Modo produção
npm start
Configurando no Claude Desktop
Para usar este servidor MCP com o Claude Desktop, você precisa configurá-lo no arquivo de configuração do Claude:
⚠️ Nota: Esta funcionalidade requer Claude Desktop versão 0.7.0 ou superior com suporte a MCP.
1. Localize o arquivo de configuração
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
2. Adicione a configuração do servidor
Edite o arquivo claude_desktop_config.json e adicione:
{
"mcpServers": {
"activecampaign": {
"command": "node",
"args": ["/caminho/para/seu/projeto/dist/index.js"],
"env": {
"ACTIVECAMPAIGN_API_URL": "https://seuaccount.api-us1.com",
"ACTIVECAMPAIGN_API_KEY": "sua-api-key-aqui"
}
}
}
}
Exemplo com caminho completo:
{
"mcpServers": {
"activecampaign": {
"command": "node",
"args": ["/Users/seunome/projetos/activecampaign-mcp-server/dist/index.js"],
"env": {
"ACTIVECAMPAIGN_API_URL": "https://seuaccount.api-us1.com",
"ACTIVECAMPAIGN_API_KEY": "abc123def456ghi789"
}
}
}
}
3. Compile o projeto
Certifique-se de que o projeto está compilado:
# Com npm
npm run build
# Com pnpm (recomendado)
pnpm build
4. Teste o servidor (opcional)
Antes de configurar no Claude Desktop, você pode testar se o servidor está funcionando:
# Teste com inspector MCP
pnpm inspect
# Ou teste direto
node dist/index.js
5. Reinicie o Claude Desktop
Feche completamente o Claude Desktop e abra novamente para carregar a nova configuração.
6. Verificar se funcionou
No Claude Desktop, você deve poder usar comandos como:
- "Busque o contato com email usuario@exemplo.com"
- "Mostre os eventos de tracking do contato ID 123"
- "Pesquise contatos com o nome João Silva"
🚨 Troubleshooting
Se as ferramentas não aparecerem:
- Verifique o caminho: Certifique-se de que o caminho para
dist/index.js está correto - Verifique a compilação: Execute
npm run build novamente - Verifique as credenciais: Confirme se a API URL e Key estão corretas
- Verifique os logs: Olhe os logs do Claude Desktop para erros
- Reinicie completamente: Feche o Claude Desktop pelo Activity Monitor/Task Manager
Configuração alternativa com variáveis de ambiente do sistema:
{
"mcpServers": {
"activecampaign": {
"command": "node",
"args": ["/caminho/para/seu/projeto/dist/index.js"]
}
}
}
Neste caso, defina as variáveis no seu sistema:
export ACTIVECAMPAIGN_API_URL="https://seuaccount.api-us1.com"
export ACTIVECAMPAIGN_API_KEY="sua-api-key-aqui"
🧪 Testando as Ferramentas
Uma vez configurado, você pode testar as ferramentas diretamente no Claude Desktop:
Exemplo de comandos:
🔍 Buscar contato:
"Busque informações do contato john@exemplo.com no ActiveCampaign"
📊 Análise de engajamento:
"Mostre os eventos de email dos últimos 30 dias para o contato ID 123"
🔍 Pesquisa avançada:
"Pesquise todos os contatos que têm 'CEO' no nome e me mostre suas informações completas"
📈 Relatório de atividade:
"Analise o comportamento de engajamento do contato maria@empresa.com nos últimos 3 meses"
Ferramentas Disponíveis
1. Buscar Contato por Email
{
"name": "get_contact_by_email",
"arguments": {
"email": "usuario@exemplo.com"
}
}
2. Buscar Contato por ID
{
"name": "get_contact_by_id",
"arguments": {
"contactId": "123"
}
}
3. Pesquisar Contatos
{
"name": "search_contacts",
"arguments": {
"query": "João Silva",
"limit": 10
}
}
4. Logs de Tracking por ID
{
"name": "get_contact_tracking_logs",
"arguments": {
"contactId": "123",
"limit": 50,
"offset": 0,
"eventType": "open",
"dateRange": {
"start": "2024-01-01",
"end": "2024-12-31"
}
}
}
5. Logs de Tracking por Email
{
"name": "get_contact_tracking_logs_by_email",
"arguments": {
"email": "usuario@exemplo.com",
"limit": 100,
"eventType": "click"
}
}
📁 Estrutura do Projeto
src/
├── index.ts # Servidor MCP principal
├── types/
│ └── index.ts # Interfaces e tipos TypeScript
└── tools/
├── index.ts # Exportações das ferramentas
├── contacts.ts # Ferramentas de contatos
└── tracking.ts # Ferramentas de tracking
Arquitetura
- Modular: Cada conjunto de ferramentas está em seu próprio arquivo
- Tipada: Interfaces TypeScript para todos os dados
- Escalável: Fácil adicionar novas ferramentas
- Testável: Classes isoladas para facilitar testes
📋 Exemplo de Resposta
Dados de Contato
{
"id": "123",
"email": "usuario@exemplo.com",
"firstName": "João",
"lastName": "Silva",
"phone": "+55 11 99999-9999",
"fieldValues": [
{
"field": "Empresa",
"value": "Exemplo Corp"
}
],
"tags": ["Cliente VIP", "Newsletter"],
"lists": [
{
"list": "Newsletter Mensal",
"status": "active"
}
],
"cdate": "2024-01-15T10:30:00Z",
"udate": "2024-01-20T14:45:00Z"
}
Logs de Tracking
{
"summary": {
"total": 25,
"count": 25,
"limit": 100,
"offset": 0,
"eventTypes": {
"open": 15,
"click": 8,
"sent": 2
}
},
"events": [
{
"id": "456",
"type": "open",
"timestamp": "2024-01-15T10:30:00-03:00",
"date": "2024-01-15T13:30:00.000Z",
"contact": "123",
"subscriberId": "123",
"hash": "abc123",
"description": "Email foi aberto",
"campaign": {
"id": "789",
"name": "Newsletter Janeiro"
}
}
]
}
🤝 Contribuindo
Contribuições são muito bem-vindas! Para contribuir:
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/nova-funcionalidade) - Commit suas mudanças (
git commit -m 'Adiciona nova funcionalidade') - Push para a branch (
git push origin feature/nova-funcionalidade) - Abra um Pull Request
Desenvolvimento
# Instalar dependências
pnpm install
# Executar em modo desenvolvimento
pnpm dev
# Executar testes
pnpm test
# Verificar linting
pnpm lint
# Build para produção
pnpm build
📝 Licença
Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
🔗 Links Úteis
📞 Suporte
Se você encontrar algum problema ou tiver dúvidas:
- Verifique se existe uma issue similar
- Crie uma nova issue com detalhes do problema
- Entre em contato através das issues do GitHub