Sfmc Mcp Server

SFMC MCP Server

Conecte o Claude (ou qualquer client MCP) ao Salesforce Marketing Cloud. Explore Data Extensions, consulte registros e valide queries do Automation Studio antes de rodá-las.

[npm version] [License: MIT]

O problema

Quem opera SFMC conhece a rotina: você escreve uma Query Activity, salva, roda a automação — e 30 minutos depois descobre que digitou EmailAdress em vez de EmailAddress. Ou que usou um ORDER BY, que o dialeto do Automation Studio não suporta. Ou que a coluna de saída não existe na DE de destino.

O feedback loop do SFMC é medido em dezenas de minutos. Este servidor MCP reduz para segundos.

O que ele faz

validate_sql em ação

Você: valide essa query pra mim
SELECT c.SubscriberKey, c.EmailAdress, c.LastPurchaseDateFROM Customers_Master cORDER BY c.CreatedDate DESC

❌ INVÁLIDA — 3 erro(s) bloqueante(s).
1. ORDER BY não é suportado em Query Activities do SFMC. [linha ~3]   → Se precisar de ranking, use ROW_NUMBER() OVER (ORDER BY ...) em subquery.
2. A coluna "EmailAdress" não existe na DE "Customers_Master".   → Você quis dizer "EmailAddress"?
3. A coluna "LastPurchaseDate" não existe na DE "Customers_Master".   → Campos disponíveis: SubscriberKey, EmailAddress, FirstName, Status, CreatedDate

O que ele detecta:

Regras do dialeto — ORDER BY, CTEs (WITH), MERGE, DML/DDL, variáveis (DECLARE @), temp tables (#temp), cursores, stored procedures, FULL OUTER JOIN, parênteses desbalanceados, SELECT * arriscado, GETDATE() em fuso do servidor.

Contra o schema real — DEs inexistentes, colunas inexistentes (com sugestão de correção via distância de edição), aliases não declarados, colunas de saída incompatíveis com a DE de destino, PK do destino ausente no SELECT (a falha silenciosa mais cara do SFMC).

Instalação

npx sfmc-mcp-server

Ou instalando localmente:

npm install -g sfmc-mcp-server

Configuração

1. Crie um Installed Package no SFMC

Setup → Apps → Installed Packages → New → Add Component → API Integration (Server-to-Server)

Permissões mínimas (somente leitura):

• Data Extensions: Read
• Automations: Read

Anote o Client ID, o Client Secret e o subdomínio (a parte antes de .auth.marketingcloudapis.com).

2. Configure o Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) %APPDATA%\Claude\claude_desktop_config.json (Windows)

{  "mcpServers": {    "sfmc": {      "command": "npx",      "args": ["-y", "sfmc-mcp-server"],      "env": {        "SFMC_SUBDOMAIN": "mcXXXXXXXXXXXXXXXXXXXXXX",        "SFMC_CLIENT_ID": "seu_client_id",        "SFMC_CLIENT_SECRET": "seu_client_secret",        "SFMC_MODE": "read"      }    }  }}

Reinicie o Claude Desktop. Pronto.

Múltiplas Business Units

Uma entrada por BU, cada uma com seu SFMC_ACCOUNT_ID (o MID):

{  "mcpServers": {    "sfmc-varejo": {      "command": "npx",      "args": ["-y", "sfmc-mcp-server"],      "env": { "SFMC_ACCOUNT_ID": "1234567", "...": "..." }    },    "sfmc-b2b": {      "command": "npx",      "args": ["-y", "sfmc-mcp-server"],      "env": { "SFMC_ACCOUNT_ID": "7654321", "...": "..." }    }  }}

Exemplos de uso

• "Valide essa query contra a DE de destino Active_Buyers" → aponta erros antes de você perder 30 min
• "Liste as DEs que têm 'master' no nome, com os campos" → schema completo sem abrir o Contact Builder
• "Quantos registros ativos tem a Customers_Master?" → consulta direta com filtro
• "Essa DE tem chave primária? Quais campos são NOT NULL?" → auditoria de schema em segundos

Segurança

• Somente leitura por padrão. SFMC_MODE=read é o default. Tools de escrita (roadmap) só serão registradas com SFMC_MODE=write.
• Credenciais apenas via variáveis de ambiente. Nunca commitadas, nunca em disco.
• Log de auditoria. Toda tool call vai para stderr com timestamp e argumentos — redirecione para arquivo ou coletor conforme sua política.
• Sem retenção. O servidor não persiste dados do SFMC.

Arquitetura

src/├── index.ts               # Entry point — registra tools, transporte stdio├── auth.ts                # OAuth client_credentials, cache de token (~20 min)├── sfmcClient.ts          # REST client com retry exponencial (429/5xx)└── tools/    ├── validateSql.ts     # Regras do dialeto + validação contra schema real    ├── listDataExtensions.ts    └── queryDataExtension.ts

Detalhes de implementação:

• Token com cache e margem de 60s antes da expiração (SFMC expira em ~18-20 min)
• Retry exponencial em 429/5xx — o SFMC estrangula com facilidade sob carga
• Auth lazy: o servidor sobe mesmo sem credenciais, valida na primeira tool call
• Paginação forçada nas consultas (máx 50 linhas) para não estourar o contexto do modelo

Roadmap

• get_automation_status — status e histórico de execução
• list_journeys — journeys ativas, versões, métricas
• get_send_stats — opens, clicks, bounces
• upsert_rows — gravação com padrão checkpoint/resume (modo write)
• Suporte a Shared Data Extensions do Parent BU via SOAP

Limitações conhecidas

• A validate_sql cobre as restrições conhecidas do Automation Studio e a existência de tabelas/colunas. Não garante correção lógica nem performance.
• DEs compartilhadas (ENT.) não são validadas contra schema — vivem no Parent BU, fora do alcance da REST da BU atual.
• Colunas não qualificadas (sem prefixo alias.) não são validadas em queries com múltiplos JOINs — resolver isso exigiria um parser SQL completo.
• O endpoint /data/v1/customobjects é relativamente recente. Instâncias em releases antigas podem precisar do fallback SOAP.

Contribuindo

PRs bem-vindos. As áreas de maior impacto são as tools do roadmap e novas regras de validação do dialeto SFMC — se você já perdeu tempo com uma construção que o Automation Studio rejeita, abra uma issue com o caso.

Licença

MIT