Salesforce Metadata MCP

salesforce-metadata-mcp

唯一一款可构建 Agentforce Agent、OmniStudio 组件和 DevOps Center 流水线的 Salesforce MCP 服务——同时提供完整的日常开发流程（架构描述、Apex 读取、调试日志），总计 228 个工具，可直接通过 Claude 或任何 MCP 客户端构建、配置和自动化 Salesforce 组织。

---

快速开始

npx -y salesforce-metadata-mcp

或全局安装：

npm install -g salesforce-metadata-mcp
salesforce-metadata-mcp

---

配置（Claude Desktop / Claude Code）

添加到 MCP 配置（claude_desktop_config.json 或 .claude/settings.json）：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["salesforce-metadata-mcp"],
      "env": {
        "SF_INSTANCE_URL": "https://your-org.salesforce.com",
        "SF_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

有关所有身份验证方法和详细设置说明，请参阅 SETUP.md。

一键安装（Claude Desktop）

从最新版本下载 salesforce-metadata-mcp-<version>.mcpb，然后将其拖入 Claude Desktop → Settings → Extensions。系统会提示你输入组织 URL 和凭据，无需编辑 JSON。

该软件包会在启动时从 npm 获取服务，而不是嵌入副本，因此始终运行当前已发布的版本，升级后也无需重新下载。

Docker

docker build -t salesforce-metadata-mcp .
docker run -i --rm \
  -e SF_INSTANCE_URL="https://your-org.my.salesforce.com" \
  -e SF_ACCESS_TOKEN="your_access_token" \
  salesforce-metadata-mcp

该镜像从源代码构建，以非 root 用户身份运行，且仅包含生产依赖。由于此服务通过 stdio 使用 MCP，因此必须使用 -i——容器由客户端驱动，而不是作为后台服务运行。SF_ALIAS 在容器中无法使用：Salesforce CLI 的登录流程需要浏览器，因此请改用 token、JWT、refresh-token 或 client-credentials 变量。

---

工具集——加载 228 个工具而不耗尽上下文

所有 228 个工具始终可用。大多数工具不会在有人调用之前加载到模型的上下文中。

一开始列出所有工具大约需要 98,000 个 token——约占 200k 上下文窗口的一半，在你输入任何内容之前就已消耗，无论会话是否会用到 OmniStudio 或 DevOps Center。列出 228 个候选工具还会明显降低模型选择正确工具的能力。因此，服务启动时只加载一小部分核心工具，其余工具按需加载：

启动方式	列出的工具数	约需 token 数
默认（core,metadata）	20	约 9,900
再加载两个工具集后	43	约 20,800
SF_TOOLSETS=all	233	约 99,100

默认工具集涵盖几乎所有会话都需要的功能：描述/列出对象、SOQL 查询、部署/检索/删除元数据、部署状态，以及核心架构创建（对象、字段、公式字段、选项列表值、验证规则、审批流程）。

五个工具始终可用，并能触达其他所有工具：

• sf_find_tool — 按名称搜索全部 228 个工具，并在一次调用中加载匹配项。请求 “创建一个 omniscript”，它就会找到相关工具、加载 omnistudio，之后即可立即调用。这通常就是你或模型所需的一切。
• sf_load_toolset — 显式加载指定的工具集。
• sf_list_toolsets — 浏览所有工具集、各自的工具数量以及已加载的工具集。
• sf_call_tool — 按名称调用任意工具，无论是否已加载，无需先将其显示在工具列表中。参数会经过验证，生产环境保护措施与直接调用时完全相同。
• sf_tool_schema — 返回任意工具的输入架构，以便为客户端不可见的工具构造 sf_call_tool 调用。

实际上，你无需手动管理这些内容：只要提出需求，模型就会加载所需工具。

如果已加载的工具未显示

加载工具集会在服务端启用它，并发出 notifications/tools/list_changed。客户端应在收到该通知后重新获取 tools/list。有些客户端不会这样做——发生这种情况时，加载操作会报告成功，工具也确实已启用，但模型仍无法调用它们，因为它们从未进入模型的工具列表。

有两种机制可以解决这个问题，确保客户端不会失去对任何工具的访问权限：

• sf_load_toolset 会检查客户端是否重新获取了工具列表，并在响应中说明检查结果，不会对已无法访问的工具仅报告成功。
• sf_call_tool 无需重新获取工具列表即可调用所有工具。结合 sf_tool_schema，仅凭握手时获取的工具列表就能使用完整的 228 个工具，包括在 SF_TOOLSETS=none 时。

若要恢复之前启动时加载所有工具的行为，请设置 SF_TOOLSETS=all。若要启动时仅加载五个元工具，请设置 SF_TOOLSETS=none。若要自选核心工具集，请传入列表：

{ "env": { "SF_TOOLSETS": "metadata,objects,automation,security" } }

可用工具集：core、metadata、objects、data、flows、automation、security、apex、lwc、ui、pages、actions、agentforce、omnistudio、omnichannel、devops、deployment、integrations、identity、reports、experience、admin、monitoring、audit、einstein、knowledge、cpq、sandbox、streaming、visualforce、aura、comms、mcp、i18n。

Flow 工具归属于独立的 flows 工具集，因为 sf_create_flow 包含完整的 Flow 元素架构，仅此一项就有 15,266 字节（约 4,126 个 token），是服务中最大的工具定义。将其排除在默认工具集之外，可避免不创建 Flow 的会话为此付出开销；需要创建 Flow 的会话仍可获得完整且经过验证的架构。

---

工具 — 共 228 个

以下是部分亮点；完整参考文档（含参数和提示词示例）请参阅 TOOLS.md。

对象与字段

工具	描述
sf_create_custom_object	创建自定义对象并配置所有设置
sf_create_custom_field	在任意对象上创建字段（支持所有类型）
sf_create_formula_field	创建公式字段，全面支持公式语言
sf_add_picklist_values	向现有选项列表字段添加值
sf_create_custom_metadata_type	创建自定义元数据类型（__mdt）
sf_create_custom_metadata_record	为自定义元数据类型创建记录
sf_create_custom_label	创建或更新自定义标签
sf_create_custom_setting	创建层级或列表自定义设置
sf_create_global_value_set	创建可供多个对象共用的选项列表
sf_create_record_type	创建记录类型并覆盖选项列表
sf_create_business_process	为 Opp/Lead/Case 创建业务流程
sf_create_page_layout	创建包含分区和字段的页面布局
sf_create_sharing_rule	创建基于条件或所有权的共享规则
sf_create_field_dependency	创建控制字段与依赖选项列表之间的依赖关系
sf_describe_object	读取对象的完整架构——字段、类型、选项列表值、子级关系和记录类型
sf_list_objects	按名称或标签片段查找对象——在调用 sf_describe_object 前进行发现
sf_get_metadata_dependencies	影响分析：哪些组件引用了此组件？此字段是否包含数据？ 只读
sf_update_custom_object	更新对象级属性，并通过确认关卡对风险进行分类
sf_update_custom_field	更新字段定义，并按风险分类——应用破坏性变更前会报告影响

自动化

工具	描述
sf_create_flow	创建任意类型的 Flow — Assignment、Decision、GetRecords、CreateRecords（含字段值）、DeleteRecords、Loop
sf_create_approval_process	创建多步骤审批流程
sf_create_validation_rule	创建数据验证规则
sf_create_workflow_field_update	创建工作流字段更新操作
sf_create_email_alert	创建工作流电子邮件提醒操作
sf_create_platform_event	创建 Platform Event 对象
sf_create_assignment_rule	创建 Lead/Case 分配规则
sf_create_escalation_rule	创建 Case 升级规则
sf_create_auto_response_rule	创建 Web-to-Lead/Case 自动响应规则
sf_create_matching_rule	创建重复项匹配规则
sf_create_duplicate_rule	创建重复项检测规则
sf_create_apex_email_service	创建入站 Apex 电子邮件服务
sf_create_scheduled_job	通过 cron 调度 Apex 类

安全与访问

工具	描述
sf_create_permission_set	创建包含所有权限的 Permission Sets
sf_create_role	在角色层级结构中创建角色
sf_create_queue	创建包含成员和对象的队列
sf_create_named_credential	创建用于 callout 的 Named Credentials
sf_get_field_permissions	审计 Profiles 和 Permission Sets 中当前授予的字段级安全权限

UI 与体验

工具	描述
sf_create_lightning_app	创建带有导航栏/实用程序栏的 Lightning Apps
sf_create_tab	为对象创建 Custom Tabs
sf_create_compact_layout	创建 Compact Layouts（重点信息面板）
sf_create_list_view	创建带筛选条件和列的 List Views
sf_create_email_template	创建 HTML/文本电子邮件模板
sf_create_static_resource	根据文本内容创建 Static Resources
sf_create_custom_notification_type	创建 Custom Notification Types
sf_create_report_type	创建 Custom Report Types
sf_create_dashboard	创建包含组件的 Dashboards

Apex 开发

工具	描述
sf_create_apex_class	将任意 Apex 类部署到组织
sf_create_apex_trigger	在任意对象上部署 Apex 触发器
sf_create_apex_test_class	部署测试类，可选择运行测试
sf_run_apex_tests	运行测试类并获取通过/失败结果
sf_execute_anonymous_apex	执行匿名 Apex 并查看输出
sf_get_apex_class	读取现有 Apex 类的源代码
sf_get_apex_trigger	读取现有 Apex 触发器的源代码
sf_enable_debug_logs	为用户启用 Apex 调试日志（TraceFlag）
sf_disable_debug_logs	关闭 Apex 调试日志（删除活动的 TraceFlags）
sf_get_debug_logs	列出近期 Apex 调试日志
sf_get_debug_log_body	读取调试日志的完整内容
sf_scan_apex_antipatterns	使用轻量级启发式方法扫描 SOQL/DML 循环、硬编码 ID 和调试语句
sf_run_code_scanner	通过 Salesforce Code Analyzer 进行多引擎静态分析（PMD、SFGE SOQL 注入数据流、RetireJS、ESLint）

LWC 开发

工具	描述
sf_create_lwc	部署包含 HTML、JS、CSS 的完整 LWC
sf_update_lwc	更新现有 LWC 组件

Experience Cloud

工具	描述
sf_create_experience_site	创建 Experience Cloud 站点
sf_create_experience_page	在 Experience 站点中创建页面

Agentforce

工具	描述
sf_create_agent	创建 Agentforce Agent（Bot shell）
sf_create_agent_action	创建关联到 Flows/Apex 的 Agent Actions（GenAiFunction）
sf_create_agent_topic	创建配置了相应操作的 Agent Topics（GenAiPlugin）
sf_create_agent_planner	将 Agent 关联到其主题（GenAiPlanner）——路由必需

外部集成

工具	描述
sf_create_connected_app	创建 OAuth Connected Apps
sf_create_external_client_app	创建 External Client Apps（OAuth）——Salesforce 对 Connected Apps 的较新替代方案；Client Credentials Flow（包括 Run As 用户）可通过 API 在此设置，而 Connected Apps 不支持
sf_create_external_data_source	为 Connect 创建 External Data Sources
sf_create_external_object	创建 External Objects（__x）
sf_create_remote_site_setting	将外部 URL 加入白名单，以供 callout 使用
sf_create_csp_setting	为 LWC 创建 CSP 可信站点

变更集与部署

工具	描述
sf_create_outbound_change_set	创建 Outbound Change Sets
sf_add_to_change_set	将组件添加到变更集
sf_deploy_metadata	通过 Metadata API 部署元数据（支持 testLevel、内联 XML）
sf_check_deploy_status	检查部署作业状态
sf_retrieve_metadata	从组织中检索元数据
sf_delete_metadata	永久删除元数据组件（CustomObject、CustomField、Flow、GenAiFunction、Bot 等）

MCP 服务管理

工具	描述
sf_create_mcp_server	在磁盘上生成新的 MCP 服务项目
sf_create_mcp_tool	向现有 MCP 服务添加新工具
sf_list_mcp_tools	列出 MCP 服务项目中的所有工具

---

示例提示词

构建完整对象：

“创建一个名为 Project__c 的自定义对象，包含以下字段：Name（文本）、Status__c（选项列表：Planning/Active/Complete）、Budget__c（货币），然后添加一条验证规则，要求 Status 为 Active 时必须填写 Budget。”

部署 Apex：

“创建一个名为 OpportunityService 的 Apex 类，用于查询所有 Amount > 100000 的 Opps。然后为其创建一个测试类。”

创建 Flow：

“在 Opportunity 上创建一个记录触发型 Flow，当 Stage = Closed Won 时在保存后触发。向所有者发送电子邮件提醒，并创建一项 30 天后到期的后续 Task。”

设置 LWC：

“创建一个名为 accountSummary 的 Lightning Web Component，用于显示账户名称、行业和年收入。使其可用于 Record Pages。”

Agentforce 设置：

“创建一个名为 SalesAssistant 的 Agentforce Agent。然后创建一个关联到 Get_Account_Orders Flow 的 GetOrders 操作。接着创建一个包含以下操作的 OrderManagement 主题：[GetOrders]。最后将 SalesAssistant 关联到 OrderManagement 主题。”

---

环境变量

变量	描述	必需
SF_INSTANCE_URL	组织 URL（例如 https://org.salesforce.com）	始终需要
SF_CLIENT_ID	Connected App 客户端 ID	用于 OAuth
SF_CLIENT_SECRET	Connected App 客户端密钥	用于 OAuth
SF_REFRESH_TOKEN	OAuth 刷新令牌	用于 OAuth
SF_ALIAS	Salesforce CLI 组织别名	用于 CLI
SF_ACCESS_TOKEN	静态访问令牌（约 1 小时后过期）	用于静态模式
PORT	HTTP 服务端口（默认：3000）	用于 HTTP 模式
TRANSPORT	stdio 或 http（默认：stdio）	可选
SF_TOOLSETS	启动时加载的工具集：all、none 或以逗号分隔的列表（默认：core,metadata）	可选
SF_TOOLSETS_VERBOSE	设为 1，即可在启动时将完整工具集列表打印到 stderr	可选
SF_PRODUCTION_GUARD	destructive（默认）、strict 或 off——见下文	可选

---

生产环境写入保护

此服务会将 Salesforce 凭据交给大模型，由大模型决定如何使用。模型在此过程中读取的任何文本——案例评论、字段描述、检索到的 .flow 文件、电子邮件正文——都可能包含指令，而后续流程无法区分它们与您输入的指令。

因此，对于生产组织，默认拒绝九种工具：

在生产环境中被阻止	原因
sf_delete_metadata	销毁元数据及其中的所有记录
sf_delete_record、sf_bulk_delete_records	销毁数据
sf_execute_anonymous_apex	执行不会留下任何产物的任意代码
sf_uninstall_package	移除托管软件包及其数据
sf_create_user、sf_update_user	提升权限
sf_reset_user_password、sf_freeze_user	接管账户／锁定账户

元数据创建不受影响。 所有 137 个 sf_create_* 工具、sf_deploy_metadata 和 sf_retrieve_metadata 在生产环境中的工作方式与以往完全相同——用自然语言编写元数据正是此软件包的目的，而阻碍这一功能的保护措施只会被关闭。

即便触发器会在每次 DML 时运行，Apex 编写（sf_create_apex_class、sf_create_apex_trigger）也不会被阻止。界限在于可审计性：创建的 Apex 属于元数据——有名称、作者和部署记录，可以被找到并移除。sf_execute_anonymous_apex 不会留下任何可查找的内容，因此它会被阻止。

只有在不是沙箱、不是 Developer Edition 组织，且不在试用版／scratch 过期状态下，组织才会被视为生产环境。沙箱、开发组织和 scratch 组织永远不会受到此限制。

{ "env": { "SF_PRODUCTION_GUARD": "strict" } }   // refuse ALL writes on production
{ "env": { "SF_PRODUCTION_GUARD": "off" } }      // no guard at all

此保护措施会直接拒绝操作，而非显示确认提示：调用 Agent 可以自行批准的提示不算控制措施，而且此服务经常在绕过客户端权限的情况下运行。只有设置环境变量才能解除此限制。

---

文档

• SETUP.md — 前置要求、身份验证、Claude 配置
• TOOLS.md — 全部 228 种工具的完整参数文档
• AGENTFORCE.md — Agentforce Agent 创建指南
• APEX_LWC.md — Apex 和 LWC 开发指南
• CHANGELOG.md — 版本历史

---

Bug 和功能请求

发现 Bug 或希望新增工具？提交 issue——其中提供 Bug 报告和功能请求模板。请注明软件包版本和工具名称，并在发布前删除任何组织 URL 或凭据。

---

许可证

MIT