Salesforce MCP Server

Salesforce MCP Server

一个 MCP（模型上下文协议）服务实现，可将 Claude 与 Salesforce 集成，通过自然语言与 Salesforce 数据和元数据交互。借助此服务，Claude 可以使用日常语言查询、修改和管理 Salesforce 对象及记录。

功能

• 对象和字段管理：使用自然语言创建和修改自定义对象及字段
• 智能对象搜索：通过部分名称匹配查找 Salesforce 对象
• 详细的架构信息：获取任意对象全面的字段和关系详情
• 灵活的数据查询：支持关系查询和复杂筛选条件的记录查询
• 数据操作：轻松插入、更新、删除和更新插入记录
• 跨对象搜索：使用 SOSL 跨多个对象搜索
• Apex 代码管理：读取、创建和更新 Apex 类与触发器
• 直观的错误处理：提供清晰的反馈和 Salesforce 专属错误详情
• 可切换的身份验证：支持多个组织。可根据 VS Code 工作区中配置的默认组织，轻松切换当前使用的 Salesforce 组织（此功能需使用 Salesforce_CLI 身份验证）。

安装

要求

• Node.js 22+（jsforce 3.10.17 及更高版本依赖 undici 8，而后者需要 Node 22；在 Node 20 上，服务会在启动时失败）。服务必须在 Node 下运行——不支持 bun：jsforce 的 HTTP 传输在 bun 下会挂起，因此身份验证看似成功，但每次 Salesforce API 调用都会卡住，直到 MCP 主机超时（参见 #118）。请在 MCP 客户端配置中使用 npx/node（不要使用 bun x）。

全局安装（npm）

npm install -g @tsmztech/mcp-server-salesforce

Claude Desktop 快速安装

如需轻松设置 Claude Desktop，请下载预配置的扩展：

1. 从 claude-desktop/ 文件夹下载 salesforce-mcp-extension.dxt
2. 打开 Claude Desktop → Settings → Extensions
3. 将 .dxt 文件拖入 Extensions 窗口
4. 根据提示配置 Salesforce 凭据

如需手动配置 Claude Desktop，请参阅下方的在 Claude Desktop 中使用。

工具

salesforce_search_objects

搜索标准对象和自定义对象：

• 按部分名称匹配进行搜索
• 查找标准对象和自定义对象
• 示例：“查找与 Account 相关的对象”会找到 Account、AccountHistory 等

salesforce_describe_object

获取详细的对象架构信息：

• 字段定义和属性
• 关系详情
• 选项列表值
• 示例：“显示 Account 对象中的所有字段”

salesforce_query_records

支持关系查询的记录查询：

• 父对象到子对象的关系
• 子对象到父对象的关系
• 复杂的 WHERE 条件
• 示例：“获取所有 Account 及其相关 Contact”
• 注意：对于包含 GROUP BY 或聚合函数的查询，请使用 salesforce_aggregate_query

salesforce_aggregate_query

执行带 GROUP BY 的聚合查询：

• 按单个或多个字段 GROUP BY
• 聚合函数：COUNT、COUNT_DISTINCT、SUM、AVG、MIN、MAX
• 使用 HAVING 子句筛选分组结果
• 日期/时间分组函数
• 示例：“按阶段统计商机数量”或“查找商机超过 10 个的客户”

salesforce_dml_records

执行数据操作：

• 插入新记录
• 更新现有记录
• 删除记录
• 使用外部 ID 更新插入记录
• 示例：“更新多个客户的状态”

salesforce_manage_object

创建和修改自定义对象：

• 创建新的自定义对象
• 更新对象属性
• 配置共享设置
• 示例：“创建一个 Customer Feedback 对象”

salesforce_manage_field

管理对象字段：

• 添加新的自定义字段
• 修改字段属性
• 创建关系
• 默认自动向 System Administrator 授予字段级安全权限
• 使用 grantAccessTo 参数指定其他配置文件
• 示例：“为 Account 添加一个 Rating 选项列表字段”

salesforce_manage_field_permissions

管理字段级安全（字段权限）：

• 为特定配置文件授予或撤销字段的读取／编辑权限
• 查看当前字段权限
• 批量更新多个配置文件的权限
• 适用于字段创建后或管理现有字段的权限
• 示例：“向 System Administrator 授予对 Account 上 Custom_Field__c 的访问权限”

salesforce_search_all

跨多个对象搜索：

• 基于 SOSL 的搜索
• 支持多个对象
• 字段摘要
• 示例：“在 Account 和 Opportunity 中搜索 ‘cloud’”

salesforce_read_apex

读取 Apex 类：

• 获取指定类的完整源代码
• 列出名称匹配指定模式的类
• 查看类元数据（API 版本、状态等）
• 名称模式支持通配符（* 和 ?）
• 示例：“显示 AccountController 类”或“查找所有名称匹配 AccountCont 的类”

salesforce_write_apex

创建和更新 Apex 类：

• 创建新的 Apex 类
• 更新现有类的实现
• 指定 API 版本
• 示例：“创建一个用于处理 Account 操作的新 Apex 类”

salesforce_read_apex_trigger

读取 Apex 触发器：

• 获取指定触发器的完整源代码
• 列出名称匹配指定模式的触发器
• 查看触发器元数据（API 版本、对象、状态等）
• 名称模式支持通配符（* 和 ?）
• 示例：“显示 AccountTrigger”或“查找所有用于 Contact 对象的触发器”

salesforce_write_apex_trigger

创建和更新 Apex 触发器：

• 为指定对象创建新的 Apex 触发器
• 更新现有触发器的实现
• 指定 API 版本和事件操作
• 示例：“为 Account 对象创建一个新触发器”或“更新 Lead 触发器”

salesforce_execute_anonymous

执行匿名 Apex 代码：

• 运行 Apex 代码，无需创建永久类
• 查看调试日志和执行结果
• 适用于执行其他工具不直接支持的数据操作
• 示例：“执行 Apex 代码以计算 Account 指标”或“运行脚本以更新相关记录”

salesforce_manage_debug_logs

管理 Salesforce 用户的调试日志：

• 为指定用户启用调试日志
• 禁用活动的调试日志配置
• 获取并查看调试日志
• 配置日志级别（NONE、ERROR、WARN、INFO、DEBUG、FINE、FINER、FINEST）
• 示例：“为 [email protected] 启用调试日志”或“获取管理员用户的近期日志”

设置

Salesforce 身份验证

你可以使用以下三种身份验证方式之一连接到 Salesforce：

1. 用户名／密码身份验证（默认）

1. 设置 Salesforce 凭据
2. 获取安全令牌（在 Salesforce 设置中重置）

2. OAuth 2.0 客户端凭据流

1. 在 Salesforce 中创建一个 Connected App
2. 启用 OAuth 设置并选择“Client Credentials Flow”
3. 设置适当的范围（通常“api”即可）
4. 保存 Client ID 和 Client Secret
5. 重要：记下实例 URL（例如，https://your-domain.my.salesforce.com），身份验证时需要使用

3. Salesforce CLI 身份验证（推荐用于本地／开发）（由 @andrea9293 贡献）

1. 安装并验证 Salesforce CLI（sf）。
2. 确保已验证组织身份，并可在 Salesforce 项目根目录通过 sf org display --json 访问。
3. 服务会自动通过 CLI 获取访问令牌和实例 URL。

可选：Salesforce API 版本

默认情况下，服务器使用 jsforce 库默认的 Salesforce API 版本，对于较新的标准对象，这个版本可能过旧（例如，AccountPlan 需要 API 版本 62.0 或更高版本，否则会报错 sObject type 'AccountPlan' is not supported）。使用任何身份验证方法时，都可以设置 SALESFORCE_API_VERSION 环境变量来指定特定版本：

"env": {
  "SALESFORCE_CONNECTION_TYPE": "...",
  "SALESFORCE_API_VERSION": "62.0"
}

值的格式必须类似 "62.0"（主版本号.次版本号）。

在 Claude Desktop 中使用

将以下内容添加到你的 claude_desktop_config.json：

使用 Salesforce CLI 身份验证：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["-y", "@tsmztech/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CONNECTION_TYPE": "Salesforce_CLI"
      }
    }
  }
}

使用用户名/密码身份验证：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["-y", "@tsmztech/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CONNECTION_TYPE": "User_Password",
        "SALESFORCE_USERNAME": "your_username",
        "SALESFORCE_PASSWORD": "your_password",
        "SALESFORCE_TOKEN": "your_security_token",
        "SALESFORCE_INSTANCE_URL": "org_url"        // Optional. Default value: https://login.salesforce.com
      }
    }
  }
}

使用 OAuth 2.0 客户端凭据流：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["-y", "@tsmztech/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CONNECTION_TYPE": "OAuth_2.0_Client_Credentials",
        "SALESFORCE_CLIENT_ID": "your_client_id",
        "SALESFORCE_CLIENT_SECRET": "your_client_secret",
        "SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com"  // REQUIRED: Must be your exact Salesforce instance URL
      }
    }
  }
}

注意：使用 OAuth 2.0 客户端凭据流时，SALESFORCE_INSTANCE_URL 必须是你的确切 Salesforce 实例 URL（例如，https://your-domain.my.salesforce.com）。令牌端点将按 <instance_url>/services/oauth2/token 构造。

使用直接访问令牌身份验证：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["-y", "@tsmztech/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CONNECTION_TYPE": "Access_Token",
        "SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com",
        "SALESFORCE_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

注意：当 OAuth 访问令牌由外部系统提供（SSO 网关、另一台机器上的 SF CLI、基于刷新令牌的代理等），且运行时只能获取最终的访问令牌和实例 URL 时，请使用 Access_Token。服务器会跳过 OAuth 握手，直接使用提供的令牌。

使用 Docker 运行

你可以在 Docker 容器中运行此 MCP 服务。由于服务器通过 stdio（标准输入/输出）通信，通常由 MCP 客户端使用 docker run -i 以交互方式启动容器。

1. 克隆仓库

git clone https://github.com/tsmztech/mcp-server-salesforce.git

2. 切换到目录

cd mcp-server-salesforce

3. 构建镜像

docker build -t mcp-server-salesforce .

4. 在容器中进行身份验证

说明

Salesforce CLI（sf）基于 Web 的 OAuth 登录流程无法在无头 Docker 容器中使用。

在容器中运行时，请使用以下受支持的基于环境变量的身份验证方法之一：

• 用户名和密码身份验证
  • SALESFORCE_CONNECTION_TYPE=User_Password
  • SALESFORCE_USERNAME
  • SALESFORCE_PASSWORD
  • SALESFORCE_TOKEN
• OAuth 2.0 客户端凭据流
  • SALESFORCE_CONNECTION_TYPE=OAuth_2.0_Client_Credentials
  • SALESFORCE_CLIENT_ID
  • SALESFORCE_CLIENT_SECRET
  • SALESFORCE_INSTANCE_URL
• 直接访问令牌身份验证
  • SALESFORCE_CONNECTION_TYPE=Access_Token
  • SALESFORCE_ACCESS_TOKEN
  • SALESFORCE_INSTANCE_URL

5. MCP 客户端配置

要将容器化的服务器注册到 MCP 客户端（例如 Claude Desktop），请将以下配置添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "salesforce": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SALESFORCE_CONNECTION_TYPE=User_Password",
        "-e",
        "SALESFORCE_USERNAME=your_username",
        "-e",
        "SALESFORCE_PASSWORD=your_password",
        "-e",
        "SALESFORCE_TOKEN=your_security_token",
        "mcp-server-salesforce"
      ]
    }
  }
}

6. 手动测试

你可以直接在终端中测试容器化的服务器：

docker run -i --rm \
  -e SALESFORCE_CONNECTION_TYPE="User_Password" \
  -e SALESFORCE_USERNAME="your_username" \
  -e SALESFORCE_PASSWORD="your_password" \
  -e SALESFORCE_TOKEN="your_security_token" \
  mcp-server-salesforce

容器运行后，你可以通过 stdin 发送 MCP initialize JSON-RPC 请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    }
  }
}

使用示例

搜索对象

"Find all objects related to Accounts"
"Show me objects that handle customer service"
"What objects are available for order management?"

获取架构信息

"What fields are available in the Account object?"
"Show me the picklist values for Case Status"
"Describe the relationship fields in Opportunity"

查询记录

"Get all Accounts created this month"
"Show me high-priority Cases with their related Contacts"
"Find all Opportunities over $100k"

聚合查询

"Count opportunities by stage"
"Show me the total revenue by account"
"Find accounts with more than 10 opportunities"
"Calculate average deal size by sales rep and quarter"
"Get the number of cases by priority and status"

管理自定义对象

"Create a Customer Feedback object"
"Add a Rating field to the Feedback object"
"Update sharing settings for the Service Request object"

字段级安全示例：

# Default - grants access to System Administrator automatically
"Create a Status picklist field on Custom_Object__c"

# Custom profiles - grants access to specified profiles
"Create a Revenue currency field on Account and grant access to Sales User and Marketing User profiles"

管理字段权限

"Grant System Administrator access to Custom_Field__c on Account"
"Give read-only access to Rating__c field for Sales User profile"
"View which profiles have access to the Custom_Field__c"
"Revoke field access for specific profiles"

跨对象搜索

"Search for 'cloud' in Accounts and Opportunities"
"Find mentions of 'network issue' in Cases and Knowledge Articles"
"Search for customer name across all relevant objects"

管理 Apex 代码

"Show me all Apex classes with 'Controller' in the name"
"Get the full code for the AccountService class"
"Create a new Apex utility class for handling date operations"
"Update the LeadConverter class to add a new method"

管理 Apex 触发器

"List all triggers for the Account object"
"Show me the code for the ContactTrigger"
"Create a new trigger for the Opportunity object"
"Update the Case trigger to handle after delete events"

执行匿名 Apex 代码

"Execute Apex code to calculate account metrics"
"Run a script to update related records"
"Execute a batch job to process large datasets"

管理调试日志

"Enable debug logs for [email protected]"
"Retrieve recent logs for an admin user"
"Disable debug logs for a specific user"
"Configure log level to DEBUG for a user"

开发

从源代码构建

# Clone the repository
git clone https://github.com/tsmztech/mcp-server-salesforce.git

# Navigate to directory
cd mcp-server-salesforce

# Install dependencies
npm install

# Build the project
npm run build

参与贡献

欢迎贡献！你可以随时提交 Pull Request。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

问题与支持

如果你遇到任何问题或需要支持，请在 GitHub 仓库中提交 issue。