README.md•10.3 kB
# ActiveCampaign MCP Server
<div align="center">
<img src="https://img.shields.io/badge/Node.js-18+-green.svg" alt="Node.js">
<img src="https://img.shields.io/badge/TypeScript-5.0+-blue.svg" alt="TypeScript">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</div>
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
1. **Clone o repositório**
```bash
git clone https://github.com/mmarqueti/activecampaign-mcp-server.git
cd activecampaign-mcp-server
```
2. **Instale as dependências**
```bash
# Com npm
npm install
# Com pnpm
pnpm install
```
3. **Configure as variáveis de ambiente**
```bash
cp .env.example .env
```
Edite o arquivo `.env` com suas credenciais:
```env
ACTIVECAMPAIGN_API_URL=https://seuaccount.api-us1.com
ACTIVECAMPAIGN_API_KEY=sua-api-key-aqui
```
4. **Compile o projeto**
```bash
# Com npm
npm run build
# Com pnpm
pnpm build
```
## ⚙️ Configuração
### Obtendo Credenciais do ActiveCampaign
1. Acesse sua conta do ActiveCampaign
2. Vá para **Settings > Developer**
3. Copie sua **API URL** e **API Key**
4. 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
```bash
# 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:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```
#### 2. Adicione a configuração do servidor
Edite o arquivo `claude_desktop_config.json` e adicione:
```json
{
"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:**
```json
{
"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:
```bash
# 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:
```bash
# 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:**
1. **Verifique o caminho**: Certifique-se de que o caminho para `dist/index.js` está correto
2. **Verifique a compilação**: Execute `npm run build` novamente
3. **Verifique as credenciais**: Confirme se a API URL e Key estão corretas
4. **Verifique os logs**: Olhe os logs do Claude Desktop para erros
5. **Reinicie completamente**: Feche o Claude Desktop pelo Activity Monitor/Task Manager
**Configuração alternativa com variáveis de ambiente do sistema:**
```json
{
"mcpServers": {
"activecampaign": {
"command": "node",
"args": ["/caminho/para/seu/projeto/dist/index.js"]
}
}
}
```
Neste caso, defina as variáveis no seu sistema:
```bash
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
```typescript
{
"name": "get_contact_by_email",
"arguments": {
"email": "usuario@exemplo.com"
}
}
```
#### 2. Buscar Contato por ID
```typescript
{
"name": "get_contact_by_id",
"arguments": {
"contactId": "123"
}
}
```
#### 3. Pesquisar Contatos
```typescript
{
"name": "search_contacts",
"arguments": {
"query": "João Silva",
"limit": 10
}
}
```
#### 4. Logs de Tracking por ID
```typescript
{
"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
```typescript
{
"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
```json
{
"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
```json
{
"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:
1. **Fork** o projeto
2. **Crie** uma branch para sua feature (`git checkout -b feature/nova-funcionalidade`)
3. **Commit** suas mudanças (`git commit -m 'Adiciona nova funcionalidade'`)
4. **Push** para a branch (`git push origin feature/nova-funcionalidade`)
5. **Abra** um Pull Request
### Desenvolvimento
```bash
# 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](LICENSE) para mais detalhes.
## 🔗 Links Úteis
- [Documentação da API do ActiveCampaign](https://developers.activecampaign.com/reference/overview)
- [Model Context Protocol](https://github.com/modelcontextprotocol/specification)
- [Issues](https://github.com/mmarqueti/activecampaign-mcp-server/issues)
## 📞 Suporte
Se você encontrar algum problema ou tiver dúvidas:
1. Verifique se existe uma [issue](https://github.com/mmarqueti/activecampaign-mcp-server/issues) similar
2. Crie uma nova issue com detalhes do problema
3. Entre em contato através das issues do GitHub
---
<div align="center">
Se precisar de soluções de MCP customizadas, entre em contato comigo. marcelo at marcelomarchetti.com
</div>
<br/>
<div align="center">
Feito com ❤️ para a comunidade de desenvolvedores e times de marketing
</div>