Salesforce MCP Server

Salesforce MCP 服务

一个模型上下文协议（MCP）服务，为 AI Agent 提供安全访问 Salesforce 数据和执行操作的能力。专为销售、市场营销和高管团队打造，让他们通过自然语言与 Salesforce CRM 交互。

功能

核心能力

• 🔍 搜索与查询：跨多个对象搜索记录、执行 SOQL 查询，以及进行全局搜索
• 📖 读取操作：检索指定记录并浏览关联关系
• 🔒 安全优先：默认以只读模式启动，便于安全测试
• 🔐 安全身份验证：集成 OAuth 2.0，并妥善管理令牌
• ⚡ 错误处理：全面处理错误并提供详细反馈

安全特性

• 默认只读：服务以安全的只读模式启动
• 可配置写入权限：准备就绪后，通过 SALESFORCE_READ_ONLY_MODE=false 启用写入操作
• 明确的操作标识：写入工具的描述中会明确标注

支持的 Salesforce 对象

• Accounts：公司和组织记录
• Contacts：个人联系信息
• Leads：潜在客户记录
• Opportunities：销售管道和交易
• Cases：客户服务和支持工单
• Activities：任务和活动

快速开始

🚀 完整的设置说明请参阅 SETUP.md

其中包括：

• Salesforce Connected App 配置
• Claude Desktop 集成
• 分步截图和故障排除

安装选项

选项 1：通过 GitHub 使用 NPX

npx github:tomnagengast/mcp-server-salesforce

选项 2：克隆并构建

git clone https://github.com/tomnagengast/mcp-server-salesforce.git
cd mcp-server-salesforce
npm install
npm run build

配置： Salesforce Connected App 配置等完整设置说明请参阅 SETUP.md。

配置

环境变量

创建一个 .env 文件，并添加以下配置：

# Salesforce Configuration
SALESFORCE_LOGIN_URL=https://login.salesforce.com
SALESFORCE_CLIENT_ID=your_connected_app_client_id
SALESFORCE_CLIENT_SECRET=your_connected_app_client_secret
SALESFORCE_USERNAME=your_salesforce_username
SALESFORCE_PASSWORD=your_salesforce_password
SALESFORCE_SECURITY_TOKEN=your_security_token

# For Sandbox (optional)
# SALESFORCE_LOGIN_URL=https://test.salesforce.com

# Server Configuration
PORT=3000
LOG_LEVEL=info

# Security - Server starts in READ-ONLY mode by default
SALESFORCE_READ_ONLY_MODE=true

🔒 安全提示：服务默认以只读模式启动。只有在您确认可以执行写入操作后，才设置 SALESFORCE_READ_ONLY_MODE=false。

Claude Desktop 集成

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

通过 NPX 安装：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["github:tomnagengast/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CLIENT_ID": "your_client_id",
        "SALESFORCE_CLIENT_SECRET": "your_client_secret",
        "SALESFORCE_USERNAME": "your_username", 
        "SALESFORCE_PASSWORD": "your_password",
        "SALESFORCE_SECURITY_TOKEN": "your_token",
        "SALESFORCE_READ_ONLY_MODE": "true"
      }
    }
  }
}

本地安装：

{
  "mcpServers": {
    "salesforce": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-salesforce/dist/index.js"],
      "cwd": "/path/to/your/mcp-server-salesforce"
    }
  }
}

完整的集成说明请参阅 SETUP.md。

用法

运行服务

# Development mode with hot reload
npm run dev

# Production mode
npm run start

可用工具

搜索工具

search_records - 跨多个 Salesforce 对象搜索

{
  "query": "Acme Corp",
  "objects": ["Account", "Contact", "Lead"],
  "limit": 20
}

soql_query - 执行自定义 SOQL 查询

{
  "query": "SELECT Id, Name, Email FROM Contact WHERE Account.Name = 'Acme Corp'"
}

global_search - 跨所有对象进行全局搜索

{
  "searchTerm": "[email protected]",
  "limit": 20
}

读取操作（始终可用）

get_record - 检索指定记录

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "fields": ["Name", "Type", "Industry"]
}

get_related_records - 获取关联记录

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "relationship": "Contacts",
  "limit": 20
}

get_record_history - 查看字段历史记录

{
  "objectType": "Opportunity",
  "recordId": "006XXXXXXXXXX",
  "limit": 20
}

写入操作（需要设置 SALESFORCE_READ_ONLY_MODE=false）

⚠️ 这些操作会修改您的 Salesforce 数据。只有在您确认了解服务的行为后，才启用这些操作。

create_record - 创建新记录

{
  "objectType": "Contact",
  "data": {
    "FirstName": "John",
    "LastName": "Doe",
    "Email": "[email protected]"
  }
}

update_record - 更新现有记录

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "data": {
    "Phone": "+1-555-0123"
  }
}

delete_record - 删除记录

{
  "objectType": "Lead",
  "recordId": "00QXXXXXXXXXX"
}

启用写入操作

准备好启用写入操作后：

1. 更新环境变量：

   # In your .env file
   SALESFORCE_READ_ONLY_MODE=false
   

2. 或在 Claude Desktop 配置中设置：

   {
     "mcpServers": {
       "salesforce": {
         "command": "node",
         "args": ["/path/to/your/mcp-server-salesforce/dist/index.js"],
         "env": {
           "SALESFORCE_READ_ONLY_MODE": "false",
           // ... other env vars
         }
       }
     }
   }
   

3. 重启服务和 Claude Desktop

使用场景

销售团队

• 管道管理：“显示本季度即将成交的所有商机”
• 客户研究：“查找 Acme Corp 的所有联系人及其近期活动”
• 跟进潜在客户：“查找昨天贸易展会中的所有潜在客户”（只读）或“为昨天贸易展会中的所有潜在客户创建任务”（写入模式）

市场营销团队

• 营销活动分析：“显示第四季度数字营销活动的投资回报率”
• 潜在客户评分：“查找评分高但尚未联系的潜在客户”
• 内容效果：“哪些营销活动带来了最多合格潜在客户？”

高管团队

• 收入预测：“下个季度各地区的销售线索情况如何？”
• 绩效指标：“显示本月已成交收入最高的员工”
• 客户健康度：“列出排名前 20 的客户及其近期互动情况”

开发

脚本

npm run build      # Build TypeScript
npm run dev        # Development with hot reload
npm run start      # Start production server
npm run lint       # Run ESLint
npm run test       # Run tests (when implemented)

项目结构

src/
├── auth/              # Salesforce authentication
├── tools/             # MCP tool implementations
│   ├── search-tools.ts    # Search and query tools
│   ├── crud-tools.ts      # CRUD operations
│   └── relationship-tools.ts # Relationship navigation
├── types/             # TypeScript type definitions
├── utils/             # Utilities and helpers
│   ├── config.ts          # Configuration management
│   ├── logger.ts          # Logging utilities
│   └── error-handler.ts   # Error handling
└── index.ts           # Main server entry point

安全

• OAuth 2.0：通过 Salesforce 安全认证
• 尊重权限：所有操作均遵循 Salesforce 用户权限
• 输入验证：防止 SOQL 注入并清理输入
• 错误处理：安全地提供错误消息，不泄露敏感数据

故障排查

常见问题

认证失败

• 验证 Salesforce 凭据
• 检查 Salesforce 是否已将你的 IP 地址加入允许列表
• 确保安全令牌仍然有效

权限被拒

• 验证用户是否拥有适当的对象权限
• 检查字段级安全设置
• 确保配置文件已启用 API 访问权限

API 限制

• 在 Salesforce 设置中监控 API 使用情况
• 如有需要，实施速率限制
• 对大型数据集考虑使用批量操作

贡献

1. 复刻此仓库
2. 创建功能分支
3. 进行修改
4. 运行测试和代码检查
5. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。