{
  "markdown": "# SFMC MCP Server\n\n> 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**.\n\n[![npm version](https://img.shields.io/npm/v/sfmc-mcp-server.svg)](https://www.npmjs.com/package/sfmc-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## O problema\n\nQuem 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.\n\nO feedback loop do SFMC é medido em dezenas de minutos. Este servidor MCP reduz para segundos.\n\n## O que ele faz\n\n| Tool | O que resolve |\n|---|---|\n| `validate_sql` | Valida uma Query Activity **antes** de executar: regras do dialeto restrito do SFMC + checagem de que as DEs e colunas realmente existem |\n| `list_data_extensions` | Lista DEs com metadados, filtro por nome, paginação e schema completo |\n| `query_data_extension` | Consulta registros com filtro, ordenação e paginação |\n\n### `validate_sql` em ação\n\n```\nVocê: valide essa query pra mim\n\nSELECT c.SubscriberKey, c.EmailAdress, c.LastPurchaseDate\nFROM Customers_Master c\nORDER BY c.CreatedDate DESC\n```\n\n```\n❌ INVÁLIDA — 3 erro(s) bloqueante(s).\n\n1. ORDER BY não é suportado em Query Activities do SFMC. [linha ~3]\n   → Se precisar de ranking, use ROW_NUMBER() OVER (ORDER BY ...) em subquery.\n\n2. A coluna \"EmailAdress\" não existe na DE \"Customers_Master\".\n   → Você quis dizer \"EmailAddress\"?\n\n3. A coluna \"LastPurchaseDate\" não existe na DE \"Customers_Master\".\n   → Campos disponíveis: SubscriberKey, EmailAddress, FirstName, Status, CreatedDate\n```\n\n**O que ele detecta:**\n\n*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.\n\n*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).\n\n---\n\n## Instalação\n\n```bash\nnpx sfmc-mcp-server\n```\n\nOu instalando localmente:\n\n```bash\nnpm install -g sfmc-mcp-server\n```\n\n## Configuração\n\n### 1. Crie um Installed Package no SFMC\n\n**Setup → Apps → Installed Packages → New → Add Component → API Integration (Server-to-Server)**\n\nPermissões mínimas (somente leitura):\n- **Data Extensions**: Read\n- **Automations**: Read\n\nAnote o **Client ID**, o **Client Secret** e o **subdomínio** (a parte antes de `.auth.marketingcloudapis.com`).\n\n### 2. Configure o Claude Desktop\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"sfmc\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sfmc-mcp-server\"],\n      \"env\": {\n        \"SFMC_SUBDOMAIN\": \"mcXXXXXXXXXXXXXXXXXXXXXX\",\n        \"SFMC_CLIENT_ID\": \"seu_client_id\",\n        \"SFMC_CLIENT_SECRET\": \"seu_client_secret\",\n        \"SFMC_MODE\": \"read\"\n      }\n    }\n  }\n}\n```\n\nReinicie o Claude Desktop. Pronto.\n\n### Múltiplas Business Units\n\nUma entrada por BU, cada uma com seu `SFMC_ACCOUNT_ID` (o MID):\n\n```json\n{\n  \"mcpServers\": {\n    \"sfmc-varejo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sfmc-mcp-server\"],\n      \"env\": { \"SFMC_ACCOUNT_ID\": \"1234567\", \"...\": \"...\" }\n    },\n    \"sfmc-b2b\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sfmc-mcp-server\"],\n      \"env\": { \"SFMC_ACCOUNT_ID\": \"7654321\", \"...\": \"...\" }\n    }\n  }\n}\n```\n\n---\n\n## Exemplos de uso\n\n- *\"Valide essa query contra a DE de destino `Active_Buyers`\"* → aponta erros antes de você perder 30 min\n- *\"Liste as DEs que têm 'master' no nome, com os campos\"* → schema completo sem abrir o Contact Builder\n- *\"Quantos registros ativos tem a `Customers_Master`?\"* → consulta direta com filtro\n- *\"Essa DE tem chave primária? Quais campos são NOT NULL?\"* → auditoria de schema em segundos\n\n---\n\n## Segurança\n\n- **Somente leitura por padrão.** `SFMC_MODE=read` é o default. Tools de escrita (roadmap) só serão registradas com `SFMC_MODE=write`.\n- **Credenciais apenas via variáveis de ambiente.** Nunca commitadas, nunca em disco.\n- **Log de auditoria.** Toda tool call vai para stderr com timestamp e argumentos — redirecione para arquivo ou coletor conforme sua política.\n- **Sem retenção.** O servidor não persiste dados do SFMC.\n\n---\n\n## Arquitetura\n\n```\nsrc/\n├── index.ts               # Entry point — registra tools, transporte stdio\n├── auth.ts                # OAuth client_credentials, cache de token (~20 min)\n├── sfmcClient.ts          # REST client com retry exponencial (429/5xx)\n└── tools/\n    ├── validateSql.ts     # Regras do dialeto + validação contra schema real\n    ├── listDataExtensions.ts\n    └── queryDataExtension.ts\n```\n\n**Detalhes de implementação:**\n- Token com cache e margem de 60s antes da expiração (SFMC expira em ~18-20 min)\n- Retry exponencial em 429/5xx — o SFMC estrangula com facilidade sob carga\n- Auth lazy: o servidor sobe mesmo sem credenciais, valida na primeira tool call\n- Paginação forçada nas consultas (máx 50 linhas) para não estourar o contexto do modelo\n\n---\n\n## Roadmap\n\n- [ ] `get_automation_status` — status e histórico de execução\n- [ ] `list_journeys` — journeys ativas, versões, métricas\n- [ ] `get_send_stats` — opens, clicks, bounces\n- [ ] `upsert_rows` — gravação com padrão checkpoint/resume (modo write)\n- [ ] Suporte a Shared Data Extensions do Parent BU via SOAP\n\n---\n\n## Limitações conhecidas\n\n- 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.\n- DEs compartilhadas (`ENT.`) não são validadas contra schema — vivem no Parent BU, fora do alcance da REST da BU atual.\n- 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.\n- O endpoint `/data/v1/customobjects` é relativamente recente. Instâncias em releases antigas podem precisar do fallback SOAP.\n\n---\n\n## Contribuindo\n\nPRs 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.\n\n## Licença\n\nMIT\n",
  "bytes": 6618,
  "sha": "0afe9ec9f9d74bee51e8fbea6a404013343df994518ccc283ad5363aef7ef418",
  "repo_slug": "inefavel/sfmc-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_inefavel_sfmc_mcp_server_4cdcf2f3/readme"
}