Agentforce MCP 服务器

此 MCP 服务器提供与 Salesforce Agentforce API 交互的工具。它允许进行身份验证、创建会话以及与 Agentforce 代理交换消息。

克隆后入门

如果您刚刚克隆此存储库，则可以使用交互式安装脚本快速配置和运行服务器：

chmod +x setup.sh
./setup.sh

安装脚本将：

检查你的 Python 版本
安装所需的依赖项
指导您输入 Salesforce 凭据
测试与 Salesforce 的连接
提供启动服务器
提供配置 Claude Desktop 的说明

或者，您可以按照以下手动步骤操作：

安装依赖项：
pip install -r requirements.txt
设置环境变量：
cp .env.example .env
收集您的 Salesforce 凭据：
- SALESFORCE_ORG_ID ：您的 18 个字符的 Salesforce 组织 ID
- SALESFORCE_AGENT_ID ：您的 Agentforce 代理的 18 个字符代理 ID
- SALESFORCE_CLIENT_ID ：来自您连接的应用程序的消费者密钥
- SALESFORCE_CLIENT_SECRET ：来自您连接的应用程序的消费者秘密
- SALESFORCE_SERVER_URL ：您的 Salesforce My Domain URL，不带 https:// 前缀
使用收集到的凭证编辑您的 .env 文件：
SALESFORCE_ORG_ID="00D5f000000J2PKEA0" SALESFORCE_AGENT_ID="0XxHn000000x9F1KAI" SALESFORCE_CLIENT_ID="3MVG9OGq41FnYVsFgnaG0AzJDWnoy37Bb18e0R.GgDJu2qB9sqppVl7ehWmJhGvPSLrrA0cBNhDJdsbZXnv52" SALESFORCE_CLIENT_SECRET="210117AC36E9E4C8AFCA02FF062B8A677BACBFFB71D2BB1162D60D316382FADE" SALESFORCE_SERVER_URL="example.my.salesforce.com"
（注意：这些是虚构的示例值。请用您的实际凭证替换。）
使服务器脚本可执行：
chmod +x agentforce_mcp_server.py
运行服务器：
python agentforce_mcp_server.py

有关查找 Salesforce 凭据的详细说明，请参阅下面的“设置 Salesforce”部分。

设置

确保您已安装 Python 3.10 或更高版本。
安装所需的依赖项：
pip install -r requirements.txt
使服务器脚本可执行：
chmod +x agentforce_mcp_server.py

配置

服务器使用环境变量进行配置。这些变量从.env文件加载。

复制示例环境文件来创建您自己的环境文件：
cp .env.example .env
编辑.env文件并填写您的值：
SALESFORCE_ORG_ID="your_org_id_here" SALESFORCE_AGENT_ID="your_agent_id_here" # The 18-character Agent ID you found in Salesforce SALESFORCE_CLIENT_ID="your_client_id_here" # The Consumer Key from your Connected App SALESFORCE_CLIENT_SECRET="your_client_secret_here" # The Consumer Secret from your Connected App SALESFORCE_SERVER_URL="your_server_url_here" # Your My Domain URL (e.g., example.my.salesforce.com)

Salesforce 配置

要使用 Agentforce API，您需要：

在您的 Salesforce 组织中创建连接的应用程序
查找您的 Agentforce 代理 ID
记下您的 Salesforce My Domain URL

有关这些步骤的详细说明，请参阅下面的“设置 Salesforce”部分。

运行服务器

使用以下命令运行服务器：

python agentforce_mcp_server.py

可用工具

MCP 服务器公开以下工具：

1. `authenticate`

使用客户端电子邮件通过 Agentforce API 进行身份验证。

参数：

client_email ：用于身份验证的客户端电子邮件

2. `create_agent_session`

与已配置的 Agentforce 代理创建会话。

参数：

client_email ：已验证客户端的电子邮件

3. `send_message_to_agent`

向 Agentforce 代理发送消息并返回响应。

参数：

client_email ：已验证客户端的电子邮件
message ：发送给代理的消息

4. `get_session_status`

获取当前会话的状态，包括身份验证状态、会话 ID 和序列 ID。

参数：

client_email ：已验证客户端的电子邮件

5. `complete_agentforce_conversation`

处理完整流程的便捷方法 - 身份验证、会话创建和消息发送。

参数：

client_email ：用于身份验证的客户端电子邮件
user_query ：发送给代理的消息

与 Claude for Desktop 一起使用

要将此服务器与 Claude for Desktop 一起使用，请更新您的claude_desktop_config.json文件：

{
  "mcpServers": {
    "agentforce": {
      "command": "python",
      "args": [
        "/path/to/your/agentforce_mcp_server.py"
      ]
    }
  }
}

将该路径替换为您机器上的服务器脚本的绝对路径。

不同平台的路径位置

macOS

配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json
示例路径： /Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py

视窗

配置文件： %APPDATA%\Claude\claude_desktop_config.json
示例路径： C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py

设置 Salesforce

创建连接的应用程序

要使用 Agentforce API，您需要在 Salesforce 组织中创建一个连接的应用程序：

以管理员身份登录您的 Salesforce 组织
前往设置
在快速查找框中，搜索“应用程序管理器”并单击它
单击新建连接的应用程序按钮
填写基本信息：
- 连接的应用程序名称：Agentforce MCP Integration（或您喜欢的任何名称）
- API 名称：Agentforce_MCP_Integration（将自动填充）
- 联系邮箱：您的电子邮件地址
检查启用 OAuth 设置
将回调 URL设置为https://localhost/oauth/callback （虽然未使用但必需）
在Selected OAuth Scopes下，添加：
- 通过API（api）管理用户数据
- 随时执行请求（refresh_token、offline_access）
点击**“保存”**
保存后，您将被重定向到已连接的应用详细信息页面
记下消费者密钥（这是您的客户端 ID），然后单击消费者密钥旁边的单击以显示以获取您的客户端密钥

查找您的代理 ID

要查找您的 Agentforce 代理 ID：

登录您的 Salesforce 组织
导航至Einstein Agent Builder
选择您要使用的代理
查看浏览器中的 URL - 它将包含以下格式的代理 ID： https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view
代理 ID 是 URL 中的 18 个字符 ID ( 0XxXXXXXXXXXXXXX )

查找您的 Salesforce My Domain URL

要查找您的 Salesforce My Domain URL：

登录您的 Salesforce 组织
前往设置
在快速查找框中，搜索“我的域名”并点击
您将看到域名格式为DOMAIN-NAME.my.salesforce.com
在您的 .env 文件中使用此 URL，但不带“https://”前缀

查找您的组织 ID

要查找您的 Salesforce 组织 ID：

登录您的 Salesforce 组织
前往设置
在快速查找框中，搜索“公司信息”并点击
查找“组织 ID”字段 - 这是您的 Salesforce 组织 ID
它将是一个由 15 或 18 个字符组成的字母数字字符串

笔记

服务器自动管理消息交换的序列 ID
为每个客户端电子邮件维护身份验证和会话状态
所有 API 交互均已记录，以用于调试目的

故障排除

如果您遇到问题：

身份验证失败：验证您的连接应用程序设置并确保客户端 ID 和密钥正确
会话创建错误：检查您的代理 ID，并确保它是 18 个字符的版本
连接问题：验证您的 Salesforce My Domain URL 是否正确（没有“https://”前缀）
权限错误：确保您的连接应用程序已启用正确的 OAuth 范围

测试设置

您可以使用附带的测试脚本测试您的设置：

python test_agentforce.py

这将尝试进行身份验证、创建会话并与您的 Agentforce 代理交换消息。

贡献和 GitHub Push

此存储库包含一个有用的脚本，可简化将更改推送到 GitHub 的过程：

chmod +x github_push.sh
./github_push.sh

github_push.sh脚本将：

检查你的系统上是否安装了 git
验证敏感文件（如.env不会被推送（它们位于.gitignore中）
提示您输入 GitHub 存储库 URL
如果需要，初始化 git 存储库，或更新远程 URL
添加所有文件并显示它们以供您审阅
提交更改并附带描述性消息
将更改推送到 GitHub

这使得您可以轻松共享您的定制或回馈项目，同时确保敏感信息的安全。