SFMC MCP服务器
用于Salesforce Marketing Cloud（SFMC）集成的模型上下文协议（MCP）服务器，使用 FastMCP 和 OAuth 2.1，设计用于作为公共服务部署在Heroku上。
概述
此MCP服务器通过模型上下文协议提供对Salesforce Marketing Cloud API的安全、经过身份验证的访问，使您能够：
- 列出并查询数据扩展名
- 检索用户信息
- 通过SFMC发送电子邮件
- 管理多业务部门（BU）账户
- 使用Claude.AI将SFMC操作集成到AI工作流程中
- 通过OAuth安全的HTTP/SSE从任何地方访问SFMC功能
特性
可用的MCP工具
注： 所有工具现在都需要JWT身份验证。每个用户的OAuth令牌用于API调用。所有工具都支持多业务部门（BU）帐户。
- list_data_扩展名 -使用经过身份验证的用户权限检索所有数据扩展名（支持多业务单元）
- 查询_数据_扩展 -使用用户的OAuth令牌查询特定的数据扩展数据（支持多业务单元）
- get_订阅者 -检索具有用户权限的订户列表（支持多BU）
- send_邮件 -使用经过身份验证的用户的SFMC帐户发送电子邮件（支持多业务部门）
- 列表_业务_单位 -发现经过身份验证的用户可以访问哪些业务部门（返回BU ID以供其他工具使用）
多业务部门支持
对于拥有多个业务部门的企业SFMC账户：
- 从OAuth令牌中自动检测到BU ID
- 可选的
business_unit_id所有工具上的参数 - 每个业务单元单独的令牌存储
- 看
MULTI_BU_SUPPORT.md获取详细文档
先决条件
- Python 3.11+
- 具有API访问权限的Salesforce营销云帐户
- SFMC API凭据（客户端ID、客户端机密、子域、帐户ID）
- Heroku帐户（用于云部署）
建筑
此服务器使用 FastMCP （MCP服务器的高级Python框架） OAuth 2.1委托身份验证，使其作为安全的公共HTTP服务可访问。与需要本地执行的基于stdio的MCP服务器不同，此服务器可以部署到云端，并通过HTTP/SSE从任何地方访问。
主要特点
- OAuth 2.1委托流：用户使用自己的SFMC帐户进行身份验证
- FastMCP框架：内置SSE/HTTP传输的高级MCP服务器框架
- API直接集成：无FuelSDK依赖性-使用本机REST/SOAP API
- 多业务部门支持：跨多个SFMC业务部门无缝工作
- 加密令牌存储：使用Fernet加密在静止状态下加密的用户令牌
- PostgreSQL数据库：安全、可扩展的令牌和用户管理
项目结构
SFMC MCP/
├── src/ # Source code
│ ├── server.py # Main FastMCP application
│ ├── core/ # Core SFMC functionality
│ │ ├── config.py # Basic server config
│ │ └── sfmc_client.py # Direct REST/SOAP API client
│ ├── auth/ # OAuth 2.1 authentication
│ │ ├── config.py # OAuth settings
│ │ ├── crypto.py # Token encryption (Fernet)
│ │ ├── fastmcp_oauth.py # FastMCP OAuth handler
│ │ ├── jwt.py # JWT token management
│ │ ├── models.py # Database models (User)
│ │ └── state.py # OAuth state management
│ └── utils/ # Utility scripts
│ └── generate_keys.py # Key generation helper
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── TESTING_GUIDE.md # Testing documentation
├── docs/ # Documentation
│ └── AI Generated Docs/ # AI-generated docs (gitignored)
├── pyproject.toml # Project config & dependencies
├── Makefile # Development commands
├── .pre-commit-config.yaml # Code quality hooks
└── requirements.txt # Production dependencies本地设置
快速开始使用Make
# Install dependencies
make install-dev
# Run tests
make test
# Format code
make format
# Run linters
make lint
# Start development server
make run手动设置
1.克隆存储库
git clone git@github.com:idoll_sfemu/SFMC_MCP.git
cd SFMC_MCP2.创建虚拟环境
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate3.安装依赖项
pip install -r requirements.txt4.配置环境变量
复制示例环境文件并填写您的SFMC OAuth凭据：
cp env_oauth.example .env编辑 .env 使用您的SFMC OAuth凭据并生成安全密钥：
# Generate secure keys
python src/utils/generate_keys.py
# Then edit .env with:
# - SFMC OAuth credentials (Client ID, Client Secret, Subdomain)
# - Generated JWT_SECRET_KEY
# - Generated ENCRYPTION_KEY
# - Generated STATE_SECRET_KEY
# - SERVER_BASE_URL (e.g., http://localhost:5000 for local dev)
# - DATABASE_URL (defaults to SQLite for local dev)注： 对于本地OAuth测试，您需要使用隧道服务，如 ngrok 因为SFMC要求OAuth回调使用HTTPS，并且不支持 localhost.
5.初始化数据库
# Database tables will be created automatically on first run
python -m src.server6.在本地运行服务器
启动FastMCP服务器：
make run
# or
python -m src.server服务器将在以下位置可用：
- 主要API：
http://localhost:5000/ - 健康检查：
http://localhost:5000/health - MCP端点：
http://localhost:5000/mcp - OAuth授权：
http://localhost:5000/auth/authorize
Heroku部署
方法1:Heroku命令行界面
- 安装Heroku命令行界面 （如果尚未安装）
brew install heroku/brew/heroku # macOS- 登录Heroku
heroku login- 创建Heroku应用程序
heroku create your-sfmc-mcp-server- 添加PostgreSQL数据库
heroku addons:create heroku-postgresql:essential-0- 生成和设置环境变量
# Generate secure keys locally
python src/utils/generate_keys.py
# Set OAuth config
heroku config:set SALESFORCE_CLIENT_ID=your_client_id
heroku config:set SALESFORCE_CLIENT_SECRET=your_client_secret
heroku config:set SALESFORCE_SUBDOMAIN=your_subdomain
heroku config:set SERVER_BASE_URL=https://your-app-name.herokuapp.com
# Set security keys (from generate_keys.py output)
heroku config:set JWT_SECRET_KEY=generated_jwt_key
heroku config:set ENCRYPTION_KEY=generated_encryption_key
heroku config:set STATE_SECRET_KEY=generated_state_key
# Set CORS (optional, defaults to Claude.ai)
heroku config:set ALLOWED_ORIGINS=https://claude.ai,https://api.anthropic.com- 部署
git push heroku main- 扩大Dyno
heroku ps:scale web=1- 验证部署
heroku open
heroku logs --tail方法2：部署按钮
点击下面的按钮直接部署到Heroku：
在安装过程中，系统将提示您输入SFMC凭据。
正在获取SFMC API凭据
- 登录Salesforce营销云
- 导航至 设置 > 应用 > 已安装的软件包
- 点击 新 创建新包
- 添加具有所需权限的API集成组件：
- 电子邮件：阅读、写作、发送 - 网络：读，写 - 联系人：读、写 - 数据扩展：读、写
- 保存并记下：
- 客户端ID - 客户端密钥 - 子域（来自您的SFMC URL，例如。， mc123456789) - 帐户ID（MID）
用法
认证流程
- 用户启动OAuth：用户导航到
/auth/authorize?client_id= - SFMC登录：用户使用其SFMC帐户进行身份验证
- 代币兑换：服务器接收OAuth令牌并将其加密存储
- JWT发布：服务器向用户/客户端发出JWT
- MCP工具：用户在工具调用中包含JWT，以便对SFMC API进行身份验证访问
API终点
GET /-服务器信息和可用工具GET /health-健康检查端点GET /mcp-SSE通信的MCP端点GET /auth/authorize-使用SFMC启动OAuth流GET /auth/callback-OAuth回调端点（内部）GET /.well-known/oauth-authorization-server-OAuth元数据（RFC 8414）
访问服务器
一旦部署到Heroku，您的服务器将通过HTTPS公开访问：
https://your-app-name.herokuapp.com/使用MCP客户端
配置您的MCP客户端（例如Claude Desktop）以通过SSE传输进行连接：
Claude Desktop的配置示例：
{
"mcpServers": {
"sfmc": {
"url": "https://your-app-name.herokuapp.com/mcp",
"transport": "sse",
"authentication": {
"type": "oauth2",
"authorizationUrl": "https://your-app-name.herokuapp.com/auth/authorize"
}
}
}
}对于本地开发（使用ngrok For OAuth）：
{
"mcpServers": {
"sfmc": {
"url": "https://your-ngrok-url.ngrok.io/mcp",
"transport": "sse",
"authentication": {
"type": "oauth2",
"authorizationUrl": "https://your-ngrok-url.ngrok.io/auth/authorize"
}
}
}
}注： 所有工具调用都需要JWT身份验证。OAuth流将自动向授权客户端提供此令牌。
使用cURL进行测试
您可以直接测试服务器端点：
# Check server status
curl https://your-app-name.herokuapp.com/
# Health check
curl https://your-app-name.herokuapp.com/health
# View API documentation
open https://your-app-name.herokuapp.com/docs通过MCP调用工具示例
一旦通过MCP客户端连接：
列表数据扩展名：
{
"tool": "list_data_extensions",
"arguments": {}
}查询数据扩展名：
{
"tool": "query_data_extension",
"arguments": {
"customer_key": "MyDataExtension",
"filter_clause": "EmailAddress = 'test@example.com'"
}
}获取订阅者：
{
"tool": "get_subscribers",
"arguments": {
"limit": 50
}
}发送电子邮件：
{
"tool": "send_email",
"arguments": {
"subscriber_key": "12345",
"email_address": "recipient@example.com",
"email_name": "Welcome Email"
}
}监控
健康检查端点
服务器提供多个端点用于监控：
GET /-服务器信息、版本和可用工具GET /health-简单的健康检查（返回{"status": "healthy"})GET /docs-交互式API文档
访问已部署的服务器：
# Health check
curl https://your-sfmc-mcp-server.herokuapp.com/health
# Server info
curl https://your-sfmc-mcp-server.herokuapp.com/
# Open interactive docs in browser
open https://your-sfmc-mcp-server.herokuapp.com/docs日志
查看Heroku日志：
heroku logs --tail演出
带有SSE传输的FastMCP提供：
- 低延迟HTTP通信
- 自动重新连接处理
- 适用于多个并发客户端的可扩展架构
- 内置OAuth 2.1身份验证
- 加密令牌存储以确保安全
故障排除
常见问题
- 身份验证错误
- 验证您的SFMC凭据是否正确 - 确保API包具有必要的权限 - 检查子域是否与SFMC实例匹配
- 连接超时
- 验证SFMC API端点URL - 检查网络连接 - 查看Heroku日志以了解详细错误
- 模块导入错误
- 确保所有依赖项都在 requirements.txt - 如果需要，重建Heroku应用程序： heroku restart
安全考虑
- 永不承诺
.env文件或凭据到Git - 对敏感数据使用Heroku配置变量
- 定期轮换API证书
- 对生产使用实施限速
- 定期审查SFMC API权限
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
该项目根据MIT许可证获得许可。
支持
对于问题和疑问：
- 在GitHub上打开一个问题
- 查看SFMC API文件：https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/apis.html
- 审查MCP规范：https://modelcontextprotocol.io/
技术栈
- FastMCP -MCP服务器的高级Python框架
- OAuth 2.1 -委托身份验证流程
- SSE（服务器发送事件） -实时HTTP通信（内置于FastMCP中）
- Uvicorn -闪电般快速的ASGI服务器
- SQLAlchemy 2.0 -异步ORM用于数据库操作
- PostgreSQL -生产数据库（Heroku）
- 直接SFMC API -本地REST和SOAP集成（无FuelSDK）
- 密码学（Fernet） -令牌的对称加密
- PyJWT -JWT令牌生成和验证
致谢
- 内置 模型上下文协议
- 由...驱动 FastMCP
- 直接集成 SFMC REST和SOAP API
- 设计用于部署 Heroku