MCP Salesforce Server

MCP Salesforce Server

一个使用 OAuth 身份验证与 Salesforce 无缝集成的 Model Context Protocol（MCP）服务。该服务通过安全、通用的接口，让 Claude 等 AI 助手能够与任何 Salesforce 组织交互。

✨ 功能

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

🚀 快速开始

前提条件

• Node.js 18+
• macOS（安全存储凭据所必需）
• 已配置 OAuth 的 Salesforce Connected App

安装选项

🎯 推荐：使用 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

🔧 替代方案：开发环境设置

适用于开发或自定义：

1. 克隆并安装依赖项：

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

2. 配置凭据：在收到提示时，使用 salesforce_setup 工具配置凭据

3. 添加到 Claude Desktop：使用本地路径（请参阅下方的配置）

🎯 开始使用

就是这么简单！首次使用任何 Salesforce 工具时，Claude 会自动处理设置和身份验证。

✨ 交互式设置流程！

• 使用 salesforce_setup 工具配置凭据
• Claude 会询问 Salesforce Connected App 的详细信息
• 凭据会安全地存储在主目录中
• 可直接通过 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 Connected App 设置

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

   • 应用名称：MCP Salesforce Integration
   • API 名称：mcp_salesforce_integration
   • 联系邮箱：你的邮箱
   • 启用 OAuth 设置：✅ 是
   • 回调 URL：http://localhost:9876/callback

     选择端口 9876 是为了避免与常见开发服务器（8080、8000、3000）和知名服务冲突。

   • 选定的 OAuth 范围：
     • 通过 API 管理用户数据（api）
     • 随时执行请求（refresh_token, offline_access）

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

凭证配置

首次使用应用时，请使用 salesforce_setup 工具配置凭证：

1. 交互式设置：Claude 会提示你输入 Salesforce 凭证
2. 客户端 ID：你的 Salesforce Connected App 消费者密钥
3. 客户端密钥：你的 Salesforce Connected App 消费者密码
4. 实例 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 Desktop 集成

🎯 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 Code MCP 配置

用于带 MCP 扩展的 VS Code：

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

📸 演示截图

以下是 MCP Salesforce Server 的分步演示，展示了一个在真实场景中验证和更新公司地址信息的用例：

步骤 1：地址验证请求

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

步骤 2：地址比较结果

Claude 发现 Salesforce 中的地址已过时，并详细比较 Salesforce 中的当前数据与公司网站上的实际地址

步骤 3：自动更新地址

Claude 成功将 Salesforce 账户更新为正确的当前地址，并显示具体修改的字段

步骤 4：在 Salesforce 中验证

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": "[email protected]",
    "Phone": "555-1234"
  }
}

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

salesforce_update

更新现有记录。

// Example: Update a contact's email
{
  "sobject": "Contact",
  "id": "003XX000008b6cYAQ",
  "data": {
    "Email": "[email protected]",
    "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 安装环境都各不相同，包含：

• 自定义对象，例如 "TimeTracking__c"、"Project__c"、"CustomerCare__c"
• 标准对象上的自定义字段
• 特定工作流和验证规则
• 独有的数据结构

AI 的常规训练模型只了解标准 Salesforce 对象。如果不了解您的具体安装环境，AI 就无法提供智能协助。

学习如何运作？

1. 一次性分析：salesforce_learn 分析您的完整安装环境
2. 本地文档：所有对象、字段和关系都存储在本地
3. 智能支持：之后 Claude 可以提供精准建议并回答复杂问题

工作流示例：

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 找不到对象或字段时

学到了什么？

• 所有 SObject（标准和自定义）
• 所有字段及其数据类型和权限
• 对象之间的关系
• 选项列表值和验证规则
• 用于改进验证的必填字段

💡 学习只需运行一次，之后的所有交互都会变得更加智能！

💡 使用示例

🚀 安装后的第一步

1. 身份验证：Claude 会在需要身份验证时自动检测
2. 开始学习：

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

3. 探索安装信息：

   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 Server 提供专业的备份系统，可保护完整的 Salesforce 安装：

备份系统有何特别之处？

• 🎯 全面覆盖：备份 Salesforce 的三种文件系统

  • 现代文件（ContentDocument/ContentVersion）
  • 旧版附件（经典附件）
  • 文档（基于文件夹的旧版文档）

• 📊 智能数据收集：

  • 所有可查询对象（标准 + 自定义）
  • 每个对象最多备份 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. 📋 合规与审计：提供数据变化的证据
2. 🔧 错误分析：“问题出现前有什么不同？”
3. 📊 数据质量：监控数据完整性
4. 🚨 变更管理：控制关键变更
5. 💡 商业智能：随时间变化的趋势分析

🎯 推荐的备份工作流

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 工具。无需手动排查！

常见场景：

1. 首次使用：首次尝试使用 Salesforce 工具时，Claude 会自动建议进行身份验证
2. 令牌过期：令牌过期时，Claude 会检测到并提示重新进行身份验证
3. 凭据无效：清晰的错误消息会引导你修复配置问题
4. 会话过期：自动检测，并友好地提示重新进行身份验证

令牌安全

🔒 安全存储令牌：身份验证令牌安全地存储在本地文件系统中，并采用严格的权限设置。

安全功能：

• 文件权限：令牌文件创建时采用 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

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

✨ 无需再手动进行终端设置！ 所有操作都可通过 Claude Desktop 无缝完成。

连接问题

1. “无法连接到 Salesforce”：检查你的 Instance URL
2. “权限不足”：检查 Salesforce 中的用户权限
3. “CORS 错误”：确保 Connected App 的回调 URL 正确

常见 SOQL 错误

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

📚 文档

• OAuth 设置指南 - Connected App 配置详解
• 设置说明 - 分步设置流程
• 使用示例 - 全面的使用示例
• 架构计划 - 技术架构详情

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改并全面测试
4. 提交 pull request，并附上详细说明

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🆘 支持

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

---

为 MCP 生态系统倾心打造 ❤️