io.github.Inefavel/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.

---

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

Tool	O que resolve
validate_sql	Valida uma Query Activity antes de executar: regras do dialeto restrito do SFMC + checagem de que as DEs e colunas realmente existem
list_data_extensions	Lista DEs com metadados, filtro por nome, paginação e schema completo
query_data_extension	Consulta registros com filtro, ordenação e paginação

validate_sql em ação

Você: valide essa query pra mim

SELECT c.SubscriberKey, c.EmailAdress, c.LastPurchaseDate
FROM Customers_Master c
ORDER 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