sfmc-mcp-server

SFMC MCP Server

将 Claude（或任何 MCP 客户端）连接到 Salesforce Marketing Cloud。浏览 Data Extensions、查询记录，并在运行前验证 Automation Studio 查询。

---

问题

SFMC 操作者都熟悉这样的日常：编写 Query Activity，保存，运行自动化——然后30 分钟后才发现把 EmailAddress 拼成了 EmailAdress。或者用了 Automation Studio 方言不支持的 ORDER BY。又或者输出列在目标 DE 中不存在。

SFMC 的反馈周期以数十分钟计。此 MCP 服务可将其缩短到几秒。

它能做什么

工具	解决的问题
validate_sql	在执行前验证 Query Activity：检查 SFMC 受限方言规则，并确认 DE 和列确实存在
list_data_extensions	列出 DE，并提供元数据、按名称筛选、分页和完整 schema
query_data_extension	按条件筛选、排序和分页查询记录

validate_sql 实战

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

它能检测：

方言规则 — ORDER BY、CTE（WITH）、MERGE、DML/DDL、变量（DECLARE @）、临时表（#temp）、游标、存储过程、FULL OUTER JOIN、括号不平衡、有风险的 SELECT *、服务器时区中的 GETDATE()。

对照真实 schema 检查 — 不存在的 DE、不存在的列（根据编辑距离提供修正建议）、未声明的别名、与目标 DE 不兼容的输出列、SELECT 中缺少目标 PK（SFMC 中代价最高的静默失败）。

---

安装

npx sfmc-mcp-server

或者在本地安装：

npm install -g sfmc-mcp-server

配置

1. 在 SFMC 中创建 Installed Package

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

最低权限（只读）：

• Data Extensions：Read
• Automations：Read

记下 Client ID、Client Secret 和子域名（即 .auth.marketingcloudapis.com 之前的部分）。

2. 配置 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"
      }
    }
  }
}

重启 Claude Desktop。完成。

多个 Business Unit

每个 BU 配置一个条目，并设置各自的 SFMC_ACCOUNT_ID（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", "...": "..." }
    }
  }
}

---

使用示例

• “针对目标 DE Active_Buyers 验证此查询” → 在你浪费 30 分钟之前指出错误
• “列出名称中包含 ‘master’ 的 DE，并显示字段” → 无需打开 Contact Builder，即可查看完整 schema
• “Customers_Master 中有多少条活跃记录？” → 直接按条件查询
• “此 DE 有主键吗？哪些字段是 NOT NULL？” → 几秒内完成 schema 审计

---

安全

• 默认只读。 SFMC_MODE=read 是默认值。只有在设置 SFMC_MODE=write 时，才会注册写入工具（计划中）。
• 凭据仅通过环境变量提供。 从不提交到代码库，也不会写入磁盘。
• 审计日志。 每次工具调用都会将时间戳和参数写入 stderr——可根据你的策略重定向到文件或收集器。
• 不保留数据。 此服务不会持久化 SFMC 数据。

---

架构

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

实现细节：

• 缓存令牌，并在过期前 60 秒预留缓冲时间（SFMC 约在 18–20 分钟后过期）
• 遇到 429/5xx 时指数退避重试——SFMC 在高负载下很容易限流
• 延迟认证：即使没有凭据，服务也能启动，并在首次工具调用时验证
• 查询强制分页（最多 50 行），避免超出模型上下文

---

路线图

• get_automation_status — 状态和执行历史
• list_journeys — 活跃客户旅程、版本、指标
• get_send_stats — 打开、点击、退信
• upsert_rows — 使用检查点/恢复模式写入（写入模式）
• 通过 SOAP 支持 Parent BU 的共享数据扩展

---

已知限制

• validate_sql 涵盖 Automation Studio 的已知限制以及表/列是否存在，但不保证逻辑正确性或性能。
• 共享 DE（ENT.）不会针对架构进行验证——它们位于 Parent BU 中，当前 BU 的 REST 无法访问。
• 在包含多个 JOIN 的查询中，不会验证未限定的列（没有 alias. 前缀）——解决此问题需要完整的 SQL 解析器。
• /data/v1/customobjects 端点相对较新。使用旧版 release 的实例可能需要回退到 SOAP。

---

贡献

欢迎提交 PR。影响最大的领域是路线图中的工具和 SFMC 方言的新验证规则——如果你曾经花时间排查 Automation Studio 会拒绝的语句，请提交 issue 并附上相关案例。

许可证

MIT