Salesforce MCP Server (Official)

什么是 Salesforce MCP Server (Official)？

Salesforce DX MCP 服务器是 Salesforce 官方的本地 Salesforce MCP 服务器，以 @salesforce/mcp 发布，让 AI 助手能够在你已授权的 Salesforce 组织（org）中查询数据、部署和检索元数据、管理组织并运行 Apex 测试。

它由 Salesforce 在开源仓库 salesforcecli/mcp（镜像为 forcedotcom/mcp）中维护，采用 Apache-2.0 许可证，文档见 Salesforce DX Developer Guide。重要： README 说明该本地服务器将于 2026 年 11 月 2 日停止维护（End of Life）。此后仓库将被归档、npm 包将被标记为已弃用；它仍可安装（固定版本 0.30.15 仍可使用），Salesforce 建议改用 forcedotcom/sf-skills 中的 skills。

如何使用 Salesforce MCP Server (Official)？

前提条件：

• Node.js 20 或更高版本（包的 engines 字段要求 >=20.0.0），以便 npx 运行它。
• 本机至少已授权一个组织：使用 Salesforce CLI 命令 sf org login web，或在 VS Code 命令面板中执行 SFDX: Authorize an Org。MCP 配置中不需要填写 API 密钥，服务器使用你本地已授权的组织。

所有客户端都使用相同的 args。--orgs 为必填；--toolsets、--tools 和布尔标志为可选：

{
  "mcpServers": {
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp",
               "--orgs", "DEFAULT_TARGET_ORG",
               "--toolsets", "orgs,metadata,data,users",
               "--tools", "run_apex_test",
               "--allow-non-ga-tools"]
    }
  }
}

这会启用 orgs、metadata、data、users 工具集中的全部工具以及 run_apex_test，并包含尚未正式发布（非 GA）的工具。

Claude Code

将上面的配置片段添加到项目根目录的 .mcp.json 文件中，然后重启 Claude Code。

Cursor

将同样的 mcpServers 配置块添加到 Cursor 的 mcp.json 文件中。README 中的 Cursor 和 Cline 示例使用 @salesforce/mcp@latest，以始终获取最新版本。

VS Code

在使用 GitHub Copilot 时，在项目中创建 .vscode/mcp.json。VS Code 使用 servers 键，而不是 mcpServers：

{
  "servers": {
    "Salesforce DX": {
      "command": "npx",
      "args": ["-y", "@salesforce/mcp",
              "--orgs", "DEFAULT_TARGET_ORG",
              "--toolsets", "orgs,metadata,data,users",
              "--tools", "run_apex_test",
              "--allow-non-ga-tools"]
    }
  }
}

其他客户端

Cline 在 cline_mcp_settings.json 中使用相同的配置块。对于 Windsurf、Trae 和 Zed，README 建议在各客户端的 MCP 设置中按相同模式配置。

标志

• --orgs：DEFAULT_TARGET_ORG、DEFAULT_TARGET_DEV_HUB、ALLOW_ALL_ORGS（请谨慎使用），或具体的用户名或别名。多个值用逗号分隔。
• --toolsets：以逗号分隔的工具集，或 all。
• --tools：单个工具名称，可与工具集组合使用。
• --allow-non-ga-tools、--debug、--dynamic-tools（实验性）、--no-telemetry（遥测默认开启）。

Salesforce MCP Server (Official) 的主要功能

• 官方 Salesforce DX MCP 服务器，通过 npx -y @salesforce/mcp 在本地运行。
• 组织白名单：服务器只能访问你在 --orgs 中指定的组织。
• 工具集可减少 LLM 上下文。README 称共有 60 多个工具，因此不建议启用 all。
• 通过 --tools 精细选择工具，并可与工具集混合使用。
• 区分 GA 与非 GA 工具。除非传入 --allow-non-ga-tools，否则非 GA 工具保持关闭。
• 实验性的 --dynamic-tools 模式先启动最小核心工具集，再按需加载工具（文档说明适用于 VS Code 和 Cline）。
• 组织操作之外的开发者工具集：LWC 和 Aura 专家、Code Analyzer、DevOps Center、移动开发以及 Apex 性能扫描。

Salesforce MCP Server (Official) 工具

• 核心（始终启用）： get_username 选择正确的组织用户名或别名，resume_tool_operation 恢复部署、创建 scratch org 等长时间运行的任务。
• 组织： list_all_orgs、create_scratch_org、create_org_snapshot、delete_org 和 open_org。除 list_all_orgs 外均为非 GA。
• 数据与用户： run_soql_query 运行 SOQL 查询。assign_permission_set 分配权限集。
• 元数据： deploy_metadata 和 retrieve_metadata 在 DX 项目与组织之间同步源代码。
• 测试： run_apex_test 和 run_agent_test。
• 开发者工具集： code-analysis（run_code_analyzer）、lwc-experts、aura-experts、devops、mobile/mobile-core、scale-products（scan_apex_class_for_antipatterns）、experts-validation 和 enrichment。

Salesforce MCP Server (Official) 的使用场景

• 用自然语言查询记录：“List the 10 most recently created accounts in my default org.”
• 部署开发中的改动：“Deploy my changes to my org and run the AccountServiceTest Apex tests.”
• 将组织中的改动拉取到版本控制：“Retrieve the metadata in the manifest from my org.”
• 管理 scratch org：“Create a scratch org aliased as MyNewOrg that lasts 3 days.”
• 管理用户：“Assign the Sales_Ops permission set to this user.”
• 审查代码质量：对 Apex 或 LWC 文件运行 Salesforce Code Analyzer 并汇总违规项。

Salesforce MCP Server (Official) 与替代方案对比

DX MCP 服务器是一个本地、面向开发者的工具，基于 Salesforce CLI 和你已授权的组织。Salesforce 还提供 Salesforce Hosted MCP Servers（2025 年 10 月以 Beta 形式发布），无需在本地运行任何程序即可向 AI 智能体开放 Salesforce API 和数据。相比 DX 工作流，该方案更适合业务用户和数据访问。基于 REST API 的社区版 Salesforce MCP 服务器也存在，但并非由 Salesforce 维护。由于这个 salesforce dx mcp 包将于 2026 年 11 月 2 日停止维护，新项目也应考虑 forcedotcom/sf-skills 中 Salesforce 的 skills。

Salesforce MCP Server (Official) 常见问题排查

• 工具因组织错误而失败： --orgs 为必填项，且每个组织都必须先在本地授权。运行 sf org login web 并检查用户名或别名。
• 使用了错误的组织： DEFAULT_TARGET_ORG 和 DEFAULT_TARGET_DEV_HUB 会在每次工具调用时根据工作目录的默认值解析。若要将服务器固定到特定组织，请传入明确的用户名或别名。
• 缺少 create_scratch_org 等工具： 它属于非 GA 工具。添加 --allow-non-ga-tools，并确保已启用其所属工具集。
• 模型变慢或混乱： 启用 all 会加载 60 多个工具。只启用需要的工具集，或尝试 --dynamic-tools。
• 看不到日志： 添加 --debug。注意并非所有 MCP 客户端都会显示 MCP 服务器日志。