MCP Salesforce服务器

![CI](https://github.com/AiondaDotCom/mcp-salesforce/actions/workflows/ci.yml)

A. 模型上下文协议（MCP）服务器 它使用OAuth身份验证提供与Salesforce的无缝集成。该服务器使像Claude这样的人工智能助手能够通过安全、通用的界面与任何Salesforce组织进行交互。

✨ 特性

🎯 无缝身份验证 -Claude会自动检测何时需要身份验证，并透明地处理它
🚀 零手动设置 -无需运行终端命令或手动OAuth流
🔐 仅限OAuth身份验证 -基于浏览器的安全设置，具有自动令牌刷新功能
🌐 通用Salesforce集成 -适用于任何Salesforce组织，包括自定义对象和字段
🧠 智能安装学习 -分析您的完整Salesforce设置以提供智能帮助
🔍 动态模式发现 -自动适应您的Salesforce配置
🔒 安全令牌存储 -基于文件的存储，具有严格的生产级安全权限
🏠 跨平台主目录存储 -存储在用户主目录中的凭据和缓存
📝 完整的CRUD操作 -查询、创建、更新和删除任何Salesforce记录
📊 架构检查 -获取有关对象和字段的详细信息
💡 情境感知建议 -提供智能字段和对象名称建议
💾 全面的备份系统 -完整的数据和文件备份，支持所有Salesforce文件系统
⏰ 时光机功能 -时间点数据恢复和历史分析
📁 多格式文件支持 -使用适当的元数据备份内容版本、附件和文档

🚀 快速开始

先决条件

Node.js 18+
macOS （安全凭证存储所需）
Salesforce互联应用 已配置OAuth

安装选项

🎯 推荐：NPX使用（无需安装）

使用NPX运行MCP服务器，无需任何永久安装：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-salesforce"]
    }
  }
}

✅ 使用NPX的好处：

🔄 始终最新：自动使用最新发布的版本
💾 没有磁盘空间：无需永久安装
🛡️ 无冲突：没有全局包冲突
⚡ 轻松更新：只需重新启动-自动获取最新版本
📋 简单配置：复制粘贴就绪的MCP配置

NPX命令行用法：

# Get version
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce --version

# Get help
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce --help

# Run OAuth setup
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce setup

🔧 备选方案：开发设置

对于开发或定制：

克隆并安装依赖项:

   git clone https://github.com/AiondaDotCom/mcp-salesforce.git
   cd mcp-salesforce
   npm install

配置凭据：使用 salesforce_setup 在系统提示时配置凭据的工具

添加到克劳德桌面 使用本地路径（请参见配置在......下面

🎯 开始使用

就是这样！当您首次使用任何Salesforce工具时，Claude将自动处理设置和身份验证。

✨ 交互式设置过程！

使用 salesforce_setup 配置凭据的工具
Claude会询问您Salesforce Connected应用程序的详细信息
凭据安全地存储在您的主目录中
直接从Claude Desktop无缝传输OAuth流

🧠 智能学习系统

使用 salesforce_learn 分析您的完整Salesforce安装
Claude学习所有自定义对象、字段和关系
根据您的特定设置提供智能建议
针对复杂Salesforce环境的上下文感知帮助

📦 NPM包状态

✅ 包已成功发布！

包裹 @aiondadotcom/mcp-salesforce 现在是 在NPM上直播 并准备好使用。

使用已发布的包

NPX现在可供所有用户使用：

# Test the published package
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce --version
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce --help

# Run OAuth setup
npx -p @aiondadotcom/mcp-salesforce mcp-salesforce setup

出版物详细信息

包名: @aiondadotcom/mcp-salesforce
版本: 1.0.7 （最新）
注册表：NPM公共登记处
组织: @aiondadotcom
访问：公开

状态:

✅ 包已发布到NPM
✅ NPX兼容性已验证
✅ 已实现二进制包装器
✅ 设置命令功能正常
✅ MCP配置就绪
✅ 可立即使用

🎉 所有NPX功能现在都适用于全球最终用户！

🔧 配置

Salesforce互联应用程序设置

在Salesforce设置中，创建一个新的Connected App：

- 应用程序名称：MCP Salesforce集成 - API名称：mcpsalesforce_集成 - 联系邮箱：您的电子邮件 - 启用OAuth设置: ✅ 是 - 回调URL: http://localhost:9876/callback > 为了避免与常见的开发服务器（8080、8000、3000）和知名服务发生冲突，特意选择了9876端口。 - 选定的OAuth作用域: - 通过api（api）管理用户数据 - 随时执行请求（refresh_token、offline_access）

保存后，复制 消费者密钥 和 消费者密钥

凭证配置

使用配置凭据 salesforce_setup 首次使用应用程序时使用的工具：

交互式设置：Claude将提示您输入Salesforce凭据
客户端ID：您的Salesforce互联应用消费者密钥
客户端密钥：您的Salesforce互联应用消费者秘密
实例URL：您的Salesforce组织URL（例如。， https://mycompany.salesforce.com)

该工具将验证您的输入并将凭据安全地存储在 ~/.mcp-salesforce.json 具有受限权限（600）。

📁 文件位置：

凭证: ~/.mcp-salesforce.json （包含OAuth令牌和凭据）
缓存: ~/.mcp-salesforce-cache/ （包含学习到的Salesforce模式和上下文）
交叉平台的：适用于Windows、macOS和Linux

交互示例：

Claude: I need to set up your Salesforce credentials first. Please use the salesforce_setup tool with your credentials.

You: Use the salesforce_setup tool with clientId: "3MVG9...", clientSecret: "1234567890...", instanceUrl: "https://mycompany.salesforce.com"

Claude: ✅ Salesforce credentials configured successfully! You can now use other Salesforce tools.

Claude桌面集成

🎯 NPX配置（推荐）

将此添加到您的Claude Desktop MCP配置中(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-salesforce"]
    }
  }
}

🔧 开发/本地配置

对于开发或定制安装：

{
  "mcpServers": {
    "salesforce": {
      "command": "node",
      "args": ["/path/to/mcp-salesforce/src/index.js"]
    }
  }
}

🌐 VS代码MCP配置

对于带有MCP扩展名的VS代码：

{
  "servers": {
    "salesforce": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-salesforce"]
    }
  }
}

📸 演示截图

以下是MCP Salesforce Server的逐步演练，展示了验证和更新公司地址信息的真实用例：

步骤1：地址验证请求

Address Verification *Claude通过将Salesforce中的Aionda GmbH帐户与当前网站地址进行比较，检查其地址是否正确*

步骤2：地址比较结果

Address Analysis *Claude确认Salesforce地址已过时，显示当前Salesforce数据与公司网站上的实际地址之间的详细比较*

步骤3：自动地址更新

Address Update *Claude已成功使用正确的当前地址更新Salesforce帐户，准确显示了哪些字段已更改*

步骤4:Salesforce中的验证

Salesforce Confirmation *Salesforce中显示更正地址信息的更新帐户记录现在准确且最新*

🛠️ 可用工具

`salesforce_learn`

🧠 学习完整的Salesforce安装 -一次性分析所有对象、字段和自定义项，并将此信息存储在本地以获得智能帮助。

// One-time analysis of the Salesforce installation
{}

// Force complete re-analysis
{
  "force_refresh": true,
  "detailed_relationships": true
}

为什么重要？

Claude学习你的自定义对象，如“TimeTracking\_\_c”、“Project\_\_c”等。
识别所有自定义字段及其数据类型
根据您的特定配置提供智能建议
运行一次，AI将永久受益

`salesforce_installation_info`

📊 学习Salesforce安装概述 -显示可用对象、自定义字段和自定义项。

// Complete overview of the installation
{}

// Details about a specific object
{
  "object_name": "TimeTracking__c"
}

// Search for specific fields
{
  "field_search": "email",
  "show_custom_only": true
}

`salesforce_query`

对任何Salesforce对象执行SOQL查询。

// Example: Get recent contacts
{
  "query": "SELECT Id, FirstName, LastName, Email FROM Contact WHERE CreatedDate = THIS_MONTH ORDER BY CreatedDate DESC LIMIT 10"
}

🧠 智能学习集成：

尚未学习安装时自动发出警告
建议可用对象和字段
帮助提供正确的API名称

`salesforce_create`

在任何Salesforce对象中创建新记录。

// Example: Create a new contact
{
  "sobject": "Contact",
  "data": {
    "FirstName": "John",
    "LastName": "Doe", 
    "Email": "john.doe@example.com",
    "Phone": "555-1234"
  }
}

🧠 智能上下文： 学习安装后，自动显示所选对象的必填字段。

`salesforce_update`

更新现有记录。

// Example: Update a contact's email
{
  "sobject": "Contact",
  "id": "003XX000008b6cYAQ",
  "data": {
    "Email": "new.email@example.com",
    "Phone": "555-5678"
  }
}

🧠 智能上下文： 考虑学习安装中的字段权限和数据类型。

`salesforce_delete`

删除记录(⚠️ 永久行动）。

// Example: Delete a record
{
  "sobject": "Contact", 
  "id": "003XX000008b6cYAQ"
}

`salesforce_describe`

获取对象和字段的架构信息。

// Example: Get Contact object schema
{
  "sobject": "Contact"
}

// Or get list of all available objects
{} // Empty parameters

`salesforce_backup`

💾 Salesforce综合备份系统 -创建包含详细恢复信息的所有数据和文件的完整备份。

// Create complete backup
{}

// Incremental backup since specific date
{
  "backup_type": "incremental",
  "since_date": "2025-01-01T00:00:00Z"
}

// Backup with specific options
{
  "options": {
    "include_files": true,
    "include_attachments": true,
    "include_documents": true,
    "parallel_downloads": 10
  }
}

备份内容：

📊 所有对象数据 -所有可查询对象，每个对象最多有20个字段
📁 现代文件 -具有完整元数据的ContentVersions
📎 传统附件 -具有正确文件扩展名的经典附件
📄 文件 -来自旧系统的基于文件夹的文档
🏗️ 模式信息 -完整的对象结构和关系
📋 备份清单 -详细的统计数据和恢复信息

备份结构：

salesforce-backup-2025-06-04T16-16-35-660Z/
├── metadata/           # Schema and object definitions
├── data/              # JSON data of all objects
├── files/
│   ├── content-versions/  # Modern files
│   ├── attachments/       # Legacy attachments
│   └── documents/         # Legacy documents
└── backup-manifest.json   # Backup overview

`salesforce_backup_list`

📋 显示可用备份 -所有本地备份的概述，包括统计数据和元数据。

// List all available backups
{}

// Details about a specific backup
{
  "backup_name": "salesforce-backup-2025-06-04T16-16-35-660Z"
}

`salesforce_time_machine`

⏰ 通过Salesforce数据进行时间旅行 -分析不同备份时间点之间的数据变化，并实现有针对性的恢复。

// Compare current state with a backup
{
  "backup_timestamp": "2025-06-04T16:16:35.660Z",
  "object_name": "Account"
}

// Show all changes since a specific backup
{
  "backup_timestamp": "2025-06-04T16:16:35.660Z",
  "show_all_changes": true
}

// Detailed analysis for specific records
{
  "backup_timestamp": "2025-06-04T16:16:35.660Z",
  "object_name": "Contact", 
  "record_id": "003XX000008b6cYAQ"
}

时光机特点：

📊 数据对比 -显示备份和当前状态之间的差异
🔍 变更历史 -何时更改了哪些字段
🗑️ 已删除记录 -查找自备份以来删除的记录
📈 增长分析 -数据开发的统计评估
🎯 定向恢复 -准确识别变化

`salesforce_auth`

使用Salesforce进行身份验证。自动检测是否需要身份验证并处理OAuth流。

// Example: Standard authentication (detects if needed)
{}

// Example: Force re-authentication even if tokens appear valid
{
  "force": true
}

✨ 主要特点：

自动检测：需要身份验证时，Claude会自动建议使用此工具
无手动设置：无需跑步 npm run setup 手动地
智能身份验证：仅在必要时进行身份验证，首先检查现有令牌
无缝集成：在后台透明工作

这个工具是 自动建议 什么时候：

您尝试在没有身份验证的情况下使用Salesforce工具
您的令牌已过期
发生身份验证错误
需要首次设置

🧠 智能学习系统

为什么学习很重要？

每个Salesforce安装都是独一无二的：

自定义对象 如“时间跟踪\_\_c”、“项目\_\_c”和“客户关怀\_\_c”
自定义字段 关于标准对象
具体工作流程 以及验证规则
单个数据结构

人工智能的正常训练模型只知道标准的Salesforce对象。如果不知道您的具体安装情况，AI就无法提供智能协助。

学习是如何运作的？

一次性分析: salesforce_learn 分析您的完整安装
当地文件：所有对象、字段和关系都存储在本地
智能支持：然后，克劳德可以提出精确的建议并回答复杂的问题

工作流程示例：

You: "Are there any time tracking entries for July 2025?"

Without Learning:
❌ Claude: "I don't know any object called 'TimeTracking'"

With Learning:
✅ Claude: "I'm checking the 'TimeTracking__c' object for entries from July 2025..."
   Automatically executes the correct SOQL query

你什么时候应该使用学习？

在初始设置期间 -安装后一次
发生重大变化后 -添加新的自定义对象时
当遇到问题时 -当克劳德找不到对象或字段时

学到了什么？

所有对象 （标准和定制）
所有字段 具有数据类型和权限
关系物体之间
选择列表值 以及验证规则
必填字段 为了更好地验证

💡 学习只运行一次，然后使所有进一步的交互更加智能！

💡 用法示例

🚀 安装后的第一步

认证：Claude会自动检测何时需要身份验证
开始学习:

   You: "Learn my Salesforce installation"
   Claude: Automatically uses the salesforce_learn tool

探索安装:

   You: "Show me an overview of my Salesforce installation"
   Claude: Uses salesforce_installation_info for a summary

🔍 具有学习安装功能的智能查询

You: "Show me all projects from this year"
Claude: Automatically recognizes your "Project__c" Custom Object and creates:
SELECT Id, Name, StartDate__c, Status__c FROM Project__c WHERE CALENDAR_YEAR(CreatedDate) = 2025

You: "Are there any time tracking entries for July 2025?"
Claude: Finds your "TimeTracking__c" object and queries:
SELECT Id, Name, Month__c, Hours__c FROM TimeTracking__c WHERE Month__c = 'July 2025'

查询示例

-- Get all accounts in the technology industry
SELECT Id, Name, Industry, Website FROM Account WHERE Industry = 'Technology'

-- Find contacts created this week
SELECT Id, Name, Email, CreatedDate FROM Contact WHERE CreatedDate = THIS_WEEK

-- Get opportunities closing this quarter
SELECT Id, Name, Amount, CloseDate FROM Opportunity WHERE CloseDate = THIS_QUARTER

使用自定义对象

服务器会自动发现自定义对象：

// Describe a custom object
{
  "sobject": "CustomProject__c"
}

// Query custom object
{
  "query": "SELECT Id, Name, CustomField__c FROM CustomProject__c LIMIT 10"
}

// Create custom object record
{
  "sobject": "CustomProject__c",
  "data": {
    "Name": "New Project",
    "CustomField__c": "Custom Value"
  }
}

💾 备份和时间机器功能

🚀 Salesforce备份系统

MCP Salesforce服务器提供 专业备份系统 这可以保护您的完整Salesforce安装：

是什么让备份系统与众不同？

🎯 全覆盖：备份所有三个Salesforce文件系统

- 现代文件 （内容文档/内容版本） - 传统附件 （经典附件） - 文件（基于文件夹的旧文档）

📊 智能数据采集:

- 所有可查询对象（标准+自定义） - 每个对象最多20个字段，用于全面的数据备份 - 二进制字段的自动过滤

⚡ 高性能:

- 具有可配置并发性的并行下载 - 使用指数回退重试逻辑 - 大数据量的批处理

创建备份

You: "Create a backup of my Salesforce data"
Claude: Automatically starts the salesforce_backup tool

备份结果：

✅ Backup successfully created!
📊 Statistics:
- 7 objects backed up
- 1,247 records exported  
- 6 files downloaded
- 4.07 MB total size
- Duration: 23 seconds

📁 Location: /backups/salesforce-backup-2025-06-04T16-16-35-660Z/

备份结构

salesforce-backup-2025-06-04T16-16-35-660Z/
├── backup-manifest.json     # Backup overview with statistics
├── metadata/
│   ├── objects-schema.json  # All object definitions
│   └── file-manifest.json   # File download protocol
├── data/                    # JSON data of all objects
│   ├── Account.json         # Account records
│   ├── Contact.json         # Contact records
│   ├── Opportunity.json     # Opportunity records
│   └── CustomObject__c.json # Custom Object data
└── files/                   # All Salesforce files
    ├── content-versions/    # Modern files (.pdf, .docx, etc.)
    ├── attachments/         # Legacy attachments
    └── documents/           # Legacy documents

⏰ 时光机功能

这 时间机器 使您能够穿越时间并分析数据变化：

主要特点

🔍 数据对比：将当前状态与历史备份进行比较
📊 变化分析：准确显示哪些字段已更改
🗑️ 已删除记录：查找自备份以来删除的记录
📈 趋势分析：数据开发的统计评估

使用时光机

You: "Compare the current Account data with the backup from June 4th"
Claude: Uses salesforce_time_machine for detailed analysis

示例结果：

⏰ Time Machine Analysis - Account Object
📅 Backup: 2025-06-04T16:16:35.660Z vs. Current

📊 Changes found:
• Modified records: 3
• New records: 2  
• Deleted records: 1

🔍 Details:
Account "Aionda GmbH" (001XX000003DHPF):
- BillingStreet: "Alte Straße 1" → "Königstraße 10a"
- BillingCity: "München" → "Stuttgart"
- LastModifiedDate: 2025-06-04 → 2025-06-04

Account "TechCorp Ltd" (001XX000003DHPG):
- Status: Active → Inactive
- LastModifiedDate: 2025-06-03 → 2025-06-04

实际使用案例

📋 合规与审计：数据变化的证据
🔧 错误分析：“问题出现之前有什么不同？”
📊 数据质量：监控数据完整性
🚨 变更管理：对关键变更的控制
💡 商业智能：随时间变化的趋势分析

🎯 推荐的备份工作流程

1. Initial Setup:
   You: "Learn my Salesforce installation"
   → Claude analyzes your complete org
   
2. Regular Backups:
   You: "Create a backup"
   → Claude backs up all data and files
   
3. Monitoring:
   You: "Show me all available backups"
   → Claude lists backup history
   
4. Analysis:
   You: "What has changed since the last backup?"
   → Claude uses Time Machine for comparison

💡 专业提示：结合学习+备份+时间机器，实现Salesforce的最大控制！

🔒 安全

令牌存储：刷新安全存储在中的令牌 cache/salesforce-tokens.json 具有受限文件权限（600）
无明文秘密：访问令牌仅保存在内存中
自动刷新：令牌在到期前自动刷新
安全清理：使用后从内存中删除的令牌
输入验证：所有输入都经过验证和消毒
迁移：基于文件的令牌存储，具有600个权限，用于安全凭证管理

🧪 测试

# Run tests
npm test

# Test authentication
npm run setup -- --test

# Validate configuration
npm run setup -- --validate

🐛 故障排除

身份验证问题

🎯 自动身份验证：Claude会自动检测身份验证问题并建议 salesforce_auth 工具。无需手动故障排除！

常见场景：

首次使用：当您首次尝试使用Salesforce工具时，Claude会自动建议进行身份验证
令牌过期：当令牌过期时，Claude会检测到这一点并提示重新身份验证
无效凭证：清晰的错误消息指导您修复配置问题
会话已过期：自动检测，友好提示重新验证

令牌安全

🔒 安全令牌存储：身份验证令牌以严格的权限安全地存储在本地文件系统中。

安全功能：

文件权限：令牌文件是通过以下方式创建的 0600 权限（仅由所有者可读/可写）
位置：令牌存储在 cache/salesforce-tokens.json （git除外）
自动安全：权限验证和自动修复（如果需要）
无网络曝光：令牌永远不会离开您的本地计算机
基于文件的安全：具有严格文件权限的安全令牌存储，用于凭据保护

安全验证：

# Check token file security
ls -la cache/salesforce-tokens.json
# Should show: -rw------- (600 permissions)

# Run security test
node test-token-security.js

这意味着：

您系统上的其他用户不能读取您的Salesforce令牌
只有您的用户帐户可以访问身份验证数据
防止未经授权访问您的Salesforce组织
符合凭证存储的安全最佳实践

Claude Desktop中的快速修复

如果您遇到身份验证错误，只需告诉Claude：

Authenticate with Salesforce

或者克劳德会自动建议： Use the salesforce_auth tool to authenticate with Salesforce

✨ 不再需要手动设置终端！ 一切都通过Claude Desktop无缝进行。

连接问题

“无法连接到Salesforce”：验证您的实例URL
“权限不足”：检查Salesforce中的用户权限
“CORS错误”：确保已连接的应用程序回调URL正确

常见SOQL错误

未找到字段：使用API名称，而不是字段标签
未找到对象：检查对象的拼写和API名称
语法错误：确保使用单引号的SOQL语法正确

📚 文档

OAuth设置指南 -详细的已连接应用程序配置
安装说明 -逐步设置过程
用法示例 -综合使用示例
建筑平面图 -技术架构细节

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature-name
进行更改并彻底测试
提交带有详细描述的拉取请求

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🆘 支持

问题：通过GitHub Issues报告错误和功能请求
文档：检查 docs/ 详细指南文件夹
社区：在GitHub讨论中加入讨论

______________________________________________________________________

制作❤️ 对于MCP生态系统

MCP Salesforce Server

快速接入

详细介绍