销售力-MCP服务器

Name: 销售力-MCP服务器
Author: realfastAI

作者：realfastAI2 星标更新：2025-05-29

安装使用来源：spider==github.com

项目介绍

技术文档摘要

realfast.ai Salesforce MCP Server 0.6.0

使用 Claude Desktop 与此服务器交互式地探索、分析和管理您的 Salesforce 组织！

Salesforce MCP Server

这是一个提供通过 OAuth2 认证安全访问 Salesforce 组织的 Model Context Protocol (MCP) 服务器，使 AI 模型能够通过标准化工具和资源查询和探索 Salesforce 数据。

✅ 当前功能：12个经过生产验证的工具、OAuth2 认证、全面的 Salesforce API 覆盖以及与 Claude Desktop 的集成

关于我们

realfast.ai 是一家结合了深厚数据和 AI 专业知识的 AI 原生 Salesforce 实施合作伙伴。

我们利用 AI 来更快更好地交付。我们也帮助您做到这一点！

🚀 特性

OAuth2 PKCE 认证：通过加密令牌存储实现安全的基于浏览器的认证
对象元数据工具：全面的 Salesforce 对象模式探索
Claude Desktop 集成：通过 MCP 协议无缝集成到 Claude Desktop
类型安全性：完整的 TypeScript 实现并进行严格的类型检查
生产就绪：全面的错误处理、日志记录和配置管理
可扩展架构：模块化设计，便于添加额外的 Salesforce 工具

✅ 当前实现的工具（总计 10 个）

核心数据访问工具：

describe_object - 包含记录类型的全面对象元数据和字段信息
list_objects - 列出所有 Salesforce 对象，支持过滤和分页
soql_query - 执行 SOQL 查询，防止注入并支持分页
get_record - 根据 ID 获取特定记录，支持字段选择和关系遍历
sosl_search - 多对象文本搜索，结果排名和字段权限

字段元数据工具：

get_picklist_values - 获取下拉列表字段值，包括依赖分析和安全过滤

查询分析工具：

validate_soql - SOQL 语法验证和安全分析，无需执行
explain_query_plan - 查询性能分析和优化建议

组织上下文工具：

get_org_limits - 监控组织 API 限制和使用统计
get_user_info - 获取当前用户资料信息，并进行隐私净化

附加功能：

自动刷新的 OAuth2 PKCE 认证流程
通过 stdio 运输方式与 Claude Desktop 集成
在可配置位置加密存储令牌
全面的日志记录和错误处理

🚧 计划功能

MCP 资源提供者
高级查询工具（SOSL 搜索）
实用工具（组织限制、用户信息）

🛠 安装

先决条件

Node.js 18.0 或更高版本
tsx（TypeScript 执行器）：npm install -g tsx
配置好 OAuth2 连接应用的 Salesforce 组织
Claude Desktop（用于 MCP 集成）

从源代码设置

git clone https://github.com/your-org/salesforce-mcp-server.git
cd salesforce-mcp-server
npm install

⚡ 快速开始

1. 配置 Salesforce 连接应用

步骤连接应用设置

登录 Salesforce：
- 前往您的 Salesforce 组织（生产版、沙盒或开发者版）
- 导航至设置（齿轮图标 → 设置）
创建新的连接应用：
- 在快速查找中搜索“应用管理器”
- 点击 应用管理器 → 新建连接应用
基本信息：
- 连接应用名称：MCP Salesforce Server（或您喜欢的名字）
- API 名称：自动生成（例如，MCP_Salesforce_Server）
- 联系电子邮件：您的电子邮件地址
- 描述：用于 AI 访问 Salesforce 数据的 MCP 服务器
API（启用 OAuth 设置）：
- ✅ 选中 启用 OAuth 设置
- 回调 URL：http://localhost:8080/callback
- 所选 OAuth 范围（添加这三个）：
  - 访问身份 URL 服务（id）
  - 随时执行请求（refresh_token）
  - 访问和管理您的数据（api）
Web 应用设置：
- ✅ 选中 要求 Web 服务器流的密钥
- ✅ 选中 要求刷新令牌流的密钥
安全设置（推荐）：
- IP 放松：放松 IP 限制
- 刷新令牌策略：刷新令牌直到撤销有效
保存并等待：
- 点击保存
- 等待 2-10 分钟以传播连接应用

获取凭证

获取客户端 ID 和密钥：
- 返回 应用管理器
- 查找您的连接应用 → 查看
- 复制 消费者密钥（这是您的 SFDC_CLIENT_ID）
- 点击 点击显示 旁边的消费者密钥（这是您的 SFDC_CLIENT_SECRET）
获取实例 URL：
- 您的 Salesforce 实例 URL 格式：
  - 生产版：https://yourcompany.my.salesforce.com
  - 沙盒版：https://yourcompany--sandbox.sandbox.my.salesforce.com
  - 开发者版：https://yourcompany-dev-ed.develop.my.salesforce.com

解决连接应用问题

常见问题：

"invalid_client_id" 错误：在创建连接应用后等待 2-10 分钟
"redirect_uri_mismatch" 错误：确保回调 URL 精确为 http://localhost:8080/callback
"insufficient_scope" 错误：验证选择了所有三个 OAuth 范围
SSL/TLS 错误：确保您的 Salesforce 组织具有正确的 SSL 证书

安全注意事项：

连接应用使用 PKCE（证明密钥交换）以增强安全性
客户端密钥仅用于刷新令牌流，而不是初始认证
所有令牌都使用 AES-256-GCM 加密本地存储
不以明文形式存储任何敏感数据

2. 设置环境变量

cp .env.sample .env
# 使用您的 Salesforce 凭证和文件路径编辑 .env

所需环境变量：

SFDC_CLIENT_ID=<您的连接应用客户端 ID>
SFDC_CLIENT_SECRET=<您的连接应用客户端密钥>
SFDC_INSTANCE_URL=https://your-org.my.salesforce.com
MCP_LOG_FILE="/绝对路径/到您的项目/server.log"
SFDC_TOKEN_FILE="/绝对路径/到您的项目/.salesforce-tokens.enc"

3. 添加到 Claude Desktop 配置

在您的 Claude Desktop claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "salesforce": {
      "command": "tsx",
      "args": ["/绝对路径/到/salesforce-mcp-server/src/stdio-server.ts"],
      "env": {
        "SFDC_CLIENT_ID": "您的连接应用客户端 ID",
        "SFDC_CLIENT_SECRET": "您的连接应用客户端密钥",
        "SFDC_INSTANCE_URL": "https://your-org.my.salesforce.com",
        "SFDC_API_VERSION": "v59.0",
        "MCP_LOG_FILE": "/绝对路径/到您的项目/server.log",
        "SFDC_TOKEN_FILE": "/绝对路径/到您的项目/.salesforce-tokens.enc"
      }
    }
  }
}

4. 测试集成

重启 Claude Desktop
启动新对话

尝试使用 describe_object 工具：

你能描述 Salesforce 中的 Account 对象吗？

服务器将在首次使用时自动打开浏览器进行 OAuth2 认证。

⚙️ 配置

环境变量

变量	描述	必需	默认值
`SFDC_CLIENT_ID`	OAuth2 连接应用客户端 ID	是	-
`SFDC_CLIENT_SECRET`	OAuth2 连接应用客户端密钥	是	-
`SFDC_INSTANCE_URL`	Salesforce 实例 URL	是	-
`SFDC_API_VERSION`	Salesforce API 版本	否	`v59.0`
`SFDC_TOKEN_FILE`	加密令牌存储路径	否	`.salesforce-tokens.enc`
`MCP_LOG_FILE`	服务器日志文件路径	否	- （日志输出到 stdout）

示例配置

参见 .env.sample 以获得完整示例：

# 必要的 Salesforce OAuth2 配置
SFDC_CLIENT_ID=3MVG9...您的客户端 ID
SFDC_CLIENT_SECRET=9CF743...您的客户端密钥
SFDC_INSTANCE_URL=https://your-org.my.salesforce.com

# 文件路径（使用绝对路径给 Claude Desktop）
MCP_LOG_FILE="/绝对路径/到您的项目/server.log"
SFDC_TOKEN_FILE="/绝对路径/到您的项目/.salesforce-tokens.enc"

# 可选设置
SFDC_API_VERSION=v59.0

🔐 认证

服务器使用 OAuth2 PKCE（证明密钥交换） 流程进行与 Salesforce 的安全认证。

OAuth2 设置过程

在 Salesforce 中创建连接应用（详见详细步骤）：
- 导航至设置 → 应用管理器 → 新建连接应用
- 配置 OAuth 设置，包括适当的范围和回调 URL
- 启用密钥要求以增强安全性
- 等待 2-10 分钟以传播
配置环境：
- 复制 消费者密钥 作为 SFDC_CLIENT_ID
- 复制 消费者密钥 作为 SFDC_CLIENT_SECRET
- 设置您的组织实例 URL 作为 SFDC_INSTANCE_URL
- 配置日志文件和令牌存储路径
认证流程细节：

初始认证：
- 第一次使用工具触发 OAuth2 PKCE 流程
- 在 localhost:8080 启动本地 HTTP 服务器
- 浏览器打开至 Salesforce 登录页面
- 用户登录并授予权限
- 授权码交换为访问/刷新令牌
- 令牌使用 AES-256-GCM 加密并本地存储
后续使用：
- 从本地存储加载加密令牌
- 使用访问令牌进行 API 调用
- 令牌过期时自动刷新
- 不需要浏览器交互
安全特性：
- PKCE 流程：防止授权码拦截
- 状态参数：防止 CSRF 攻击
- 本地存储：不存储云中的凭据
- 加密：AES-256-GCM，每个令牌随机 IV
- 范围限制：仅限最小必要权限
解决认证问题：

浏览器问题：
- 如果浏览器未打开：手动访问 http://localhost:8080/auth
- 如果回调失败：检查防火墙设置以允许端口 8080
- 如果登录循环：清除 Salesforce cookie 并重试
令牌问题：
- 删除令牌文件以强制重新认证：rm .salesforce-tokens.enc
- 检查令牌文件权限（应仅由用户读取）
- 验证实例 URL 是否与您的组织完全匹配
权限错误：
- 确保连接应用具有所有三个必需的 OAuth 范围
- 检查用户是否在 Salesforce 中启用了 API 访问
- 验证配置文件权限以访问对象

安全特性

PKCE（RFC 7636）：防止授权码拦截
AES-256-GCM 加密：安全本地令牌存储
状态参数：防止 CSRF 攻击
自动令牌刷新：无缝重新认证

🛠 可用工具

✅ 当前实现

`describe_object`

获取任何 Salesforce 对象的全面元数据和模式信息。

输入：

{
  "objectName": "Account"
}

对象属性（名称、标签、键前缀、权限）
完整字段元数据（类型、长度、约束、关系）
字段级别权限和可编辑性
记录类型信息
标准 vs 自定义对象分类

示例用法：

你能描述 Account 对象结构吗？
创建新联系人时哪些字段是必填的？
Opportunity 对象的字段类型和约束是什么？

`list_objects`

列出所有可用的 Salesforce 对象，支持过滤和分页。

输入：

{
  "objectType": "all",  // "all", "standard", 或 "custom"
  "limit": 100          // 1-500，默认 100
}

对象名称和标签
标准 vs 自定义分类
分页结果及计数信息
按对象类型过滤

示例用法：

这个 Salesforce 组织有哪些对象？
给我看所有自定义对象
列出前 50 个标准对象

`soql_query`

执行 SOQL 查询，具有全面的安全验证和分页支持。

输入：

{
  "query": "SELECT Id, Name FROM Account WHERE Type = 'Customer' LIMIT 10",
  "limit": 200  // 可选：1-2000，默认 200
}

特性：

安全性：SOQL 注入预防，检测危险模式
分页：可配置的记录限制（1-2000）
验证：查询语法和结构验证
干净输出：移除 Salesforce 元数据以提高可读性

示例用法：

展示所有类型为 'Customer' 的账户
查询本月创建的最后 5 个机会
找到所有电子邮件地址包含 '@salesforce.com' 的联系人

`get_record`

根据 ID 获取特定的 Salesforce 记录，支持可选字段选择。

输入：

{
  "objectName": "Account",
  "recordId": "001000000001AAA",
  "fields": ["Id", "Name", "Type", "CreatedDate"]  // 可选
}

特性：

ID 验证：Salesforce ID 格式验证（15 或 18 位字符）
字段选择：指定要检索的字段（可选）
关系支持：处理关系字段和嵌套对象
干净格式化：以适当字段组织的可读输出

示例用法：

获取 ID 为 001000000001AAA 的账户记录
展示 ID 为 003000000001BBB 的联系人记录，仅显示姓名和电子邮件字段
检索 ID 为 006000000001CCC 的机会的全部详情

🚧 计划工具

以下工具计划在未来实现：

高级查询工具

search：跨多个对象执行 SOSL 搜索

发现工具

get_picklist_values：获取指定字段的下拉列表值

实用工具

get_limits：获取组织限制和使用统计
get_user_info：获取当前用户信息

📊 资源

MCP 资源计划在未来实现以暴露 Salesforce 数据：

对象：salesforce://object/{objectType} - 对象元数据和模式
记录：salesforce://record/{objectType}/{recordId} - 单个记录数据
报告：salesforce://report/{reportId} - 报告定义和结果

目前，所有功能均可通过工具接口访问。

🧪 开发

设置

git clone https://github.com/your-org/salesforce-mcp-server.git
cd salesforce-mcp-server
npm install

可用脚本

npm run dev          # 启动带有自动重载的开发服务器
npm run build        # 构建生产版本
npm run test         # 运行单元测试（335 项测试