{"id":30871662,"url":"https://github.com/AiondaDotCom/mcp-salesforce","last_synced_at":"2025-09-07T22:28:46.793Z","repository":{"id":297101264,"uuid":"995639127","full_name":"AiondaDotCom/mcp-salesforce","owner":"AiondaDotCom","description":"🚀 Complete MCP (Model Context Protocol) server for Salesforce integration with Claude Desktop. Provides seamless OAuth authentication, universal CRUD operations on any Salesforce object.","archived":false,"fork":false,"pushed_at":"2025-07-16T12:33:26.000Z","size":1282,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T02:46:18.728Z","etag":null,"topics":["api-integration","claude-desktop","crm","linux","macos","mcp","model-context-protocol","nodejs","oauth","salesforce"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AiondaDotCom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T19:45:23.000Z","updated_at":"2025-08-21T06:27:40.000Z","dependencies_parsed_at":"2025-06-04T05:28:54.287Z","dependency_job_id":"d589883b-dba4-4249-96ae-6566b1502f05","html_url":"https://github.com/AiondaDotCom/mcp-salesforce","commit_stats":null,"previous_names":["aiondadotcom/mcp-salesforce"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/AiondaDotCom/mcp-salesforce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiondaDotCom%2Fmcp-salesforce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiondaDotCom%2Fmcp-salesforce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiondaDotCom%2Fmcp-salesforce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiondaDotCom%2Fmcp-salesforce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AiondaDotCom","download_url":"https://codeload.github.com/AiondaDotCom/mcp-salesforce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiondaDotCom%2Fmcp-salesforce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274106509,"owners_count":25223436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-integration","claude-desktop","crm","linux","macos","mcp","model-context-protocol","nodejs","oauth","salesforce"],"created_at":"2025-09-07T22:05:20.413Z","updated_at":"2025-09-07T22:28:46.768Z","avatar_url":"https://github.com/AiondaDotCom.png","language":"JavaScript","funding_links":[],"categories":["🔐 Authentication","CRM \u0026 ERP"],"sub_categories":["Playwright"],"readme":"# MCP Salesforce Server\n\n[![CI](https://github.com/AiondaDotCom/mcp-salesforce/actions/workflows/ci.yml/badge.svg)](https://github.com/AiondaDotCom/mcp-salesforce/actions/workflows/ci.yml)\n\nA **Model Context Protocol (MCP) server** that provides seamless integration with Salesforce using OAuth authentication. This server enables AI assistants like Claude to interact with any Salesforce organization through a secure, generic interface.\n\n## ✨ Features\n\n- **🎯 Seamless Authentication** - Claude automatically detects when authentication is needed and handles it transparently\n- **🚀 Zero Manual Setup** - No need to run terminal commands or manual OAuth flows\n- **🔐 OAuth-Only Authentication** - Secure browser-based setup with automatic token refresh\n- **🌐 Universal Salesforce Integration** - Works with any Salesforce org, including custom objects and fields  \n- **🧠 Smart Installation Learning** - Analyzes your complete Salesforce setup to provide intelligent assistance\n- **🔍 Dynamic Schema Discovery** - Automatically adapts to your Salesforce configuration\n- **🔒 Secure Token Storage** - File-based storage with strict permissions for production-grade security\n- **🏠 Cross-Platform Home Directory Storage** - Credentials and cache stored in user's home directory\n- **📝 Full CRUD Operations** - Query, create, update, and delete any Salesforce records\n- **📊 Schema Inspection** - Get detailed information about objects and fields\n- **💡 Context-Aware Suggestions** - Provides intelligent field and object name suggestions\n- **💾 Comprehensive Backup System** - Complete data and file backup with support for all Salesforce file systems\n- **⏰ Time Machine Feature** - Point-in-time data recovery and historical analysis\n- **📁 Multi-Format File Support** - Backs up ContentVersions, Attachments, and Documents with proper metadata\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js 18+**\n- **macOS** (required for secure credential storage)\n- **Salesforce Connected App** with OAuth configured\n\n### Installation Options\n\n#### 🎯 **Recommended: NPX Usage (No Installation Required)**\n\nUse NPX to run the MCP server without any permanent installation:\n\n```json\n{\n  \"mcpServers\": {\n    \"salesforce\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aiondadotcom/mcp-salesforce\"]\n    }\n  }\n}\n```\n\n**✅ Benefits of NPX Usage:**\n- 🔄 **Always Latest**: Automatically uses the latest published version\n- 💾 **No Disk Space**: No permanent installation required\n- 🛡️ **No Conflicts**: No global package conflicts\n- ⚡ **Easy Updates**: Just restart - gets latest version automatically\n- 📋 **Simple Config**: Copy-paste ready MCP configuration\n\n**NPX Command Line Usage:**\n```bash\n# Get version\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce --version\n\n# Get help\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce --help\n\n# Run OAuth setup\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce setup\n```\n\n#### 🔧 **Alternative: Development Setup**\n\nFor development or customization:\n\n1. **Clone and install dependencies**:\n   ```bash\n   git clone https://github.com/AiondaDotCom/mcp-salesforce.git\n   cd mcp-salesforce\n   npm install\n   ```\n\n2. **Configure credentials**: Use the `salesforce_setup` tool to configure your credentials when prompted\n\n3. **Add to Claude Desktop** using local path (see [Configuration](#configuration) below)\n\n### 🎯 **Start Using**\n\nThat's it! Claude will automatically handle setup and authentication when you first use any Salesforce tool.\n\n**✨ Interactive Setup Process!** \n- Use the `salesforce_setup` tool to configure your credentials\n- Claude will ask you for your Salesforce Connected App details\n- Credentials are stored securely in your home directory\n- Seamless OAuth flow directly from Claude Desktop\n\n**🧠 Smart Learning System**\n- Use `salesforce_learn` to analyze your complete Salesforce installation\n- Claude learns all your custom objects, fields, and relationships\n- Provides intelligent suggestions based on your specific setup\n- Context-aware assistance for complex Salesforce environments\n\n## 📦 NPM Package Status\n\n✅ **Package Successfully Published!**\n\nThe package `@aiondadotcom/mcp-salesforce` is now **live on NPM** and ready for use.\n\n### Using the Published Package\n\nNPX usage is now available for all users:\n\n```bash\n# Test the published package\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce --version\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce --help\n\n# Run OAuth setup\nnpx -p @aiondadotcom/mcp-salesforce mcp-salesforce setup\n```\n\n### Publication Details\n\n- **Package Name**: `@aiondadotcom/mcp-salesforce`\n- **Version**: `1.0.7` (latest)\n- **Registry**: NPM Public Registry\n- **Organization**: `@aiondadotcom`\n- **Access**: Public\n\n**Status**: \n- ✅ Package published to NPM\n- ✅ NPX compatibility verified \n- ✅ Binary wrapper implemented\n- ✅ Setup command functional\n- ✅ MCP configuration ready\n- ✅ **Available for immediate use**\n\n🎉 All NPX functionality now works for end users worldwide!\n\n## 🔧 Configuration\n\n### Salesforce Connected App Setup\n\n1. In Salesforce Setup, create a new Connected App:\n   - **App Name**: MCP Salesforce Integration\n   - **API Name**: mcp_salesforce_integration\n   - **Contact Email**: Your email\n   - **Enable OAuth Settings**: ✅ Yes\n   - **Callback URL**: `http://localhost:8080/callback` (will be auto-generated)\n   - **Selected OAuth Scopes**:\n     - Manage user data via APIs (api)\n     - Perform requests at any time (refresh_token, offline_access)\n\n2. After saving, copy the **Consumer Key** and **Consumer Secret**\n\n### Credential Configuration\n\nConfigure your credentials using the `salesforce_setup` tool when you first use the application:\n\n1. **Interactive Setup**: Claude will prompt you for your Salesforce credentials\n2. **Client ID**: Your Salesforce Connected App Consumer Key\n3. **Client Secret**: Your Salesforce Connected App Consumer Secret  \n4. **Instance URL**: Your Salesforce organization URL (e.g., `https://mycompany.salesforce.com`)\n\nThe tool will validate your input and store credentials securely in `~/.mcp-salesforce.json` with restricted permissions (600).\n\n**📁 File Locations:**\n- **Credentials**: `~/.mcp-salesforce.json` (contains OAuth tokens and credentials)\n- **Cache**: `~/.mcp-salesforce-cache/` (contains learned Salesforce schema and context)\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n\n**Example interaction:**\n```\nClaude: I need to set up your Salesforce credentials first. Please use the salesforce_setup tool with your credentials.\n\nYou: Use the salesforce_setup tool with clientId: \"3MVG9...\", clientSecret: \"1234567890...\", instanceUrl: \"https://mycompany.salesforce.com\"\n\nClaude: ✅ Salesforce credentials configured successfully! You can now use other Salesforce tools.\n```\n\n### Claude Desktop Integration\n\n#### 🎯 **NPX Configuration (Recommended)**\n\nAdd this to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"salesforce\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aiondadotcom/mcp-salesforce\"]\n    }\n  }\n}\n```\n\n#### 🔧 **Development/Local Configuration**\n\nFor development or customized installations:\n\n```json\n{\n  \"mcpServers\": {\n    \"salesforce\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-salesforce/src/index.js\"]\n    }\n  }\n}\n```\n\n#### 🌐 **VS Code MCP Configuration**\n\nFor VS Code with MCP extension:\n\n```json\n{\n  \"servers\": {\n    \"salesforce\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aiondadotcom/mcp-salesforce\"]\n    }\n  }\n}\n```\n\n## 📸 Demo Screenshots\n\nHere's a step-by-step walkthrough of the MCP Salesforce Server in action, showing a real-world use case of verifying and updating company address information:\n\n### Step 1: Address Verification Request\n![Address Verification](docs/step1.png)\n*Claude checking if the Aionda GmbH account in Salesforce has the correct address by comparing it with their current website address*\n\n### Step 2: Address Comparison Results  \n![Address Analysis](docs/step2.png)\n*Claude identifying that the Salesforce address is outdated, showing detailed comparison between the current Salesforce data and the actual address from the company website*\n\n### Step 3: Automated Address Update\n![Address Update](docs/step3.png)\n*Claude successfully updating the Salesforce account with the correct current address, showing exactly which fields were changed*\n\n### Step 4: Verification in Salesforce\n![Salesforce Confirmation](docs/step4.png)\n*The updated account record in Salesforce showing the corrected address information is now accurate and up-to-date*\n\n## 🛠️ Available Tools\n\n### `salesforce_learn`\n**🧠 Learns your complete Salesforce installation** - Analyzes all objects, fields and customizations once and stores this information locally for intelligent assistance.\n\n```javascript\n// One-time analysis of the Salesforce installation\n{}\n\n// Force complete re-analysis\n{\n  \"force_refresh\": true,\n  \"detailed_relationships\": true\n}\n```\n\n**Why important?** \n- Claude learns your Custom Objects like \"TimeTracking__c\", \"Project__c\", etc.\n- Recognizes all Custom Fields and their data types\n- Provides intelligent suggestions based on your specific configuration\n- Run once, then the AI benefits from it permanently\n\n### `salesforce_installation_info`\n**📊 Overview of your learned Salesforce installation** - Shows available objects, Custom Fields and customizations.\n\n```javascript\n// Complete overview of the installation\n{}\n\n// Details about a specific object\n{\n  \"object_name\": \"TimeTracking__c\"\n}\n\n// Search for specific fields\n{\n  \"field_search\": \"email\",\n  \"show_custom_only\": true\n}\n```\n\n### `salesforce_query`\nExecute SOQL queries against any Salesforce object.\n\n```javascript\n// Example: Get recent contacts\n{\n  \"query\": \"SELECT Id, FirstName, LastName, Email FROM Contact WHERE CreatedDate = THIS_MONTH ORDER BY CreatedDate DESC LIMIT 10\"\n}\n```\n\n**🧠 Smart Learning Integration:** \n- Automatically warns when installation has not been learned yet\n- Suggests available objects and fields\n- Helps with correct API names\n\n### `salesforce_create`  \nCreate new records in any Salesforce object.\n\n```javascript\n// Example: Create a new contact\n{\n  \"sobject\": \"Contact\",\n  \"data\": {\n    \"FirstName\": \"John\",\n    \"LastName\": \"Doe\", \n    \"Email\": \"john.doe@example.com\",\n    \"Phone\": \"555-1234\"\n  }\n}\n```\n\n**🧠 Smart Context:** Automatically shows required fields for the selected object when the installation has been learned.\n\n### `salesforce_update`\nUpdate existing records.\n\n```javascript\n// Example: Update a contact's email\n{\n  \"sobject\": \"Contact\",\n  \"id\": \"003XX000008b6cYAQ\",\n  \"data\": {\n    \"Email\": \"new.email@example.com\",\n    \"Phone\": \"555-5678\"\n  }\n}\n```\n\n**🧠 Smart Context:** Considers field permissions and data types from the learned installation.\n\n### `salesforce_delete`\nDelete records (⚠️ permanent action).\n\n```javascript\n// Example: Delete a record\n{\n  \"sobject\": \"Contact\", \n  \"id\": \"003XX000008b6cYAQ\"\n}\n```\n\n### `salesforce_describe`\nGet schema information for objects and fields.\n\n```javascript\n// Example: Get Contact object schema\n{\n  \"sobject\": \"Contact\"\n}\n\n// Or get list of all available objects\n{} // Empty parameters\n```\n\n### `salesforce_backup`\n**💾 Comprehensive Backup System for Salesforce** - Creates complete backups of all data and files with detailed recovery information.\n\n```javascript\n// Create complete backup\n{}\n\n// Incremental backup since specific date\n{\n  \"backup_type\": \"incremental\",\n  \"since_date\": \"2025-01-01T00:00:00Z\"\n}\n\n// Backup with specific options\n{\n  \"options\": {\n    \"include_files\": true,\n    \"include_attachments\": true,\n    \"include_documents\": true,\n    \"parallel_downloads\": 10\n  }\n}\n```\n\n**What is backed up:**\n- **📊 All Object Data** - All queryable objects with up to 20 fields per object\n- **📁 Modern Files** - ContentVersions with complete metadata\n- **📎 Legacy Attachments** - Classic attachments with correct file extensions\n- **📄 Documents** - Folder-based documents from the legacy system\n- **🏗️ Schema Information** - Complete object structures and relationships\n- **📋 Backup Manifest** - Detailed statistics and recovery information\n\n**Backup Structure:**\n```\nsalesforce-backup-2025-06-04T16-16-35-660Z/\n├── metadata/           # Schema and object definitions\n├── data/              # JSON data of all objects\n├── files/\n│   ├── content-versions/  # Modern files\n│   ├── attachments/       # Legacy attachments\n│   └── documents/         # Legacy documents\n└── backup-manifest.json   # Backup overview\n```\n\n### `salesforce_backup_list`\n**📋 Show Available Backups** - Overview of all local backups with statistics and metadata.\n\n```javascript\n// List all available backups\n{}\n\n// Details about a specific backup\n{\n  \"backup_name\": \"salesforce-backup-2025-06-04T16-16-35-660Z\"\n}\n```\n\n### `salesforce_time_machine`\n**⏰ Time Travel Through Salesforce Data** - Analyzes data changes between different backup time points and enables targeted recovery.\n\n```javascript\n// Compare current state with a backup\n{\n  \"backup_timestamp\": \"2025-06-04T16:16:35.660Z\",\n  \"object_name\": \"Account\"\n}\n\n// Show all changes since a specific backup\n{\n  \"backup_timestamp\": \"2025-06-04T16:16:35.660Z\",\n  \"show_all_changes\": true\n}\n\n// Detailed analysis for specific records\n{\n  \"backup_timestamp\": \"2025-06-04T16:16:35.660Z\",\n  \"object_name\": \"Contact\", \n  \"record_id\": \"003XX000008b6cYAQ\"\n}\n```\n\n**Time Machine Features:**\n- **📊 Data Comparison** - Shows differences between backup and current state\n- **🔍 Change History** - Which fields were changed when\n- **🗑️ Deleted Records** - Finds records that were deleted since the backup\n- **📈 Growth Analysis** - Statistical evaluation of data development\n- **🎯 Targeted Recovery** - Precise identification of changes\n\n### `salesforce_auth`\nAuthenticate with Salesforce. Automatically detects if authentication is needed and handles OAuth flow.\n\n```javascript\n// Example: Standard authentication (detects if needed)\n{}\n\n// Example: Force re-authentication even if tokens appear valid\n{\n  \"force\": true\n}\n```\n\n**✨ Key Features:**\n- **Automatic Detection**: Claude automatically suggests this tool when authentication is needed\n- **No Manual Setup**: Eliminates the need to run `npm run setup` manually  \n- **Smart Authentication**: Only authenticates when necessary, checks existing tokens first\n- **Seamless Integration**: Works transparently in the background\n\nThis tool is **automatically suggested** when:\n- You try to use Salesforce tools without authentication\n- Your tokens have expired\n- Authentication errors occur\n- First-time setup is needed\n\n## 🧠 Smart Learning System\n\n### Why is Learning Important?\n\nEvery Salesforce installation is unique with:\n- **Custom Objects** like \"TimeTracking__c\", \"Project__c\", \"CustomerCare__c\"\n- **Custom Fields** on standard objects\n- **Specific Workflows** and validation rules\n- **Individual Data Structures**\n\nThe AI's normal training model only knows standard Salesforce objects. Without knowledge of your specific installation, the AI cannot provide intelligent assistance.\n\n### How Does Learning Work?\n\n1. **One-time Analysis**: `salesforce_learn` analyzes your complete installation\n2. **Local Documentation**: All objects, fields and relationships are stored locally\n3. **Intelligent Support**: Claude can then make precise suggestions and answer complex questions\n\n### Example Workflow:\n\n```\nYou: \"Are there any time tracking entries for July 2025?\"\n\nWithout Learning:\n❌ Claude: \"I don't know any object called 'TimeTracking'\"\n\nWith Learning:\n✅ Claude: \"I'm checking the 'TimeTracking__c' object for entries from July 2025...\"\n   Automatically executes the correct SOQL query\n```\n\n### When Should You Use Learning?\n\n- **During initial setup** - Once after installation\n- **After major changes** - When new Custom Objects are added\n- **When having problems** - When Claude doesn't find objects or fields\n\n### What is Learned?\n\n- **All SObjects** (Standard and Custom)\n- **All Fields** with data types and permissions\n- **Relationships** between objects\n- **Picklist Values** and validation rules\n- **Required Fields** for better validation\n\n**💡 Learning runs only once and then makes all further interactions much more intelligent!**\n\n## 💡 Usage Examples\n\n### 🚀 First Steps After Installation\n\n1. **Authentication**: Claude automatically detects when authentication is needed\n2. **Start Learning**: \n   ```\n   You: \"Learn my Salesforce installation\"\n   Claude: Automatically uses the salesforce_learn tool\n   ```\n3. **Explore Installation**:\n   ```\n   You: \"Show me an overview of my Salesforce installation\"\n   Claude: Uses salesforce_installation_info for a summary\n   ```\n\n### 🔍 Intelligent Queries with Learned Installation\n\n```\nYou: \"Show me all projects from this year\"\nClaude: Automatically recognizes your \"Project__c\" Custom Object and creates:\nSELECT Id, Name, StartDate__c, Status__c FROM Project__c WHERE CALENDAR_YEAR(CreatedDate) = 2025\n```\n\n```\nYou: \"Are there any time tracking entries for July 2025?\"\nClaude: Finds your \"TimeTracking__c\" object and queries:\nSELECT Id, Name, Month__c, Hours__c FROM TimeTracking__c WHERE Month__c = 'July 2025'\n```\n\n### Query Examples\n\n```soql\n-- Get all accounts in the technology industry\nSELECT Id, Name, Industry, Website FROM Account WHERE Industry = 'Technology'\n\n-- Find contacts created this week\nSELECT Id, Name, Email, CreatedDate FROM Contact WHERE CreatedDate = THIS_WEEK\n\n-- Get opportunities closing this quarter\nSELECT Id, Name, Amount, CloseDate FROM Opportunity WHERE CloseDate = THIS_QUARTER\n```\n\n### Working with Custom Objects\n\nThe server automatically discovers custom objects:\n\n```javascript\n// Describe a custom object\n{\n  \"sobject\": \"CustomProject__c\"\n}\n\n// Query custom object\n{\n  \"query\": \"SELECT Id, Name, CustomField__c FROM CustomProject__c LIMIT 10\"\n}\n\n// Create custom object record\n{\n  \"sobject\": \"CustomProject__c\",\n  \"data\": {\n    \"Name\": \"New Project\",\n    \"CustomField__c\": \"Custom Value\"\n  }\n}\n```\n\n## 💾 Backup \u0026 Time Machine Features\n\n### 🚀 Salesforce Backup System\n\nThe MCP Salesforce Server offers a **professional backup system** that can secure your complete Salesforce installation:\n\n#### What Makes the Backup System Special?\n\n- **🎯 Complete Coverage**: Backs up all three Salesforce file systems\n  - **Modern Files** (ContentDocument/ContentVersion) \n  - **Legacy Attachments** (classic attachments)\n  - **Documents** (folder-based legacy documents)\n\n- **📊 Intelligent Data Collection**: \n  - All queryable objects (Standard + Custom)\n  - Up to 20 fields per object for comprehensive data backup\n  - Automatic filtering of binary fields\n\n- **⚡ High Performance**:\n  - Parallel downloads with configurable concurrency\n  - Retry logic with exponential backoff\n  - Batch processing for large data volumes\n\n#### Creating a Backup\n\n```\nYou: \"Create a backup of my Salesforce data\"\nClaude: Automatically starts the salesforce_backup tool\n```\n\n**Backup Result:**\n```\n✅ Backup successfully created!\n📊 Statistics:\n- 7 objects backed up\n- 1,247 records exported  \n- 6 files downloaded\n- 4.07 MB total size\n- Duration: 23 seconds\n\n📁 Location: /backups/salesforce-backup-2025-06-04T16-16-35-660Z/\n```\n\n#### Backup Structure\n\n```\nsalesforce-backup-2025-06-04T16-16-35-660Z/\n├── backup-manifest.json     # Backup overview with statistics\n├── metadata/\n│   ├── objects-schema.json  # All object definitions\n│   └── file-manifest.json   # File download protocol\n├── data/                    # JSON data of all objects\n│   ├── Account.json         # Account records\n│   ├── Contact.json         # Contact records\n│   ├── Opportunity.json     # Opportunity records\n│   └── CustomObject__c.json # Custom Object data\n└── files/                   # All Salesforce files\n    ├── content-versions/    # Modern files (.pdf, .docx, etc.)\n    ├── attachments/         # Legacy attachments\n    └── documents/           # Legacy documents\n```\n\n### ⏰ Time Machine Feature\n\nThe **Time Machine** enables you to travel through time and analyze data changes:\n\n#### Main Features\n\n- **🔍 Data Comparison**: Compares current state with historical backups\n- **📊 Change Analysis**: Shows exactly which fields have changed\n- **🗑️ Deleted Records**: Finds records that were deleted since the backup\n- **📈 Trend Analysis**: Statistical evaluation of data development\n\n#### Using Time Machine\n\n```\nYou: \"Compare the current Account data with the backup from June 4th\"\nClaude: Uses salesforce_time_machine for detailed analysis\n```\n\n**Example Result:**\n```\n⏰ Time Machine Analysis - Account Object\n📅 Backup: 2025-06-04T16:16:35.660Z vs. Current\n\n📊 Changes found:\n• Modified records: 3\n• New records: 2  \n• Deleted records: 1\n\n🔍 Details:\nAccount \"Aionda GmbH\" (001XX000003DHPF):\n- BillingStreet: \"Alte Straße 1\" → \"Königstraße 10a\"\n- BillingCity: \"München\" → \"Stuttgart\"\n- LastModifiedDate: 2025-06-04 → 2025-06-04\n\nAccount \"TechCorp Ltd\" (001XX000003DHPG):\n- Status: Active → Inactive\n- LastModifiedDate: 2025-06-03 → 2025-06-04\n```\n\n#### Practical Use Cases\n\n1. **📋 Compliance \u0026 Audit**: Evidence of data changes\n2. **🔧 Error Analysis**: \"What was different before the problem?\"\n3. **📊 Data Quality**: Monitoring data integrity\n4. **🚨 Change Management**: Control over critical changes\n5. **💡 Business Intelligence**: Trend analysis over time\n\n### 🎯 Recommended Backup Workflow\n\n```\n1. Initial Setup:\n   You: \"Learn my Salesforce installation\"\n   → Claude analyzes your complete org\n   \n2. Regular Backups:\n   You: \"Create a backup\"\n   → Claude backs up all data and files\n   \n3. Monitoring:\n   You: \"Show me all available backups\"\n   → Claude lists backup history\n   \n4. Analysis:\n   You: \"What has changed since the last backup?\"\n   → Claude uses Time Machine for comparison\n```\n\n**💡 Pro Tip**: Combine Learning + Backup + Time Machine for maximum Salesforce control!\n\n## 🔒 Security\n\n- **Token Storage**: Refresh tokens stored securely in `cache/salesforce-tokens.json` with restricted file permissions (600)\n- **No Plaintext Secrets**: Access tokens kept in memory only\n- **Automatic Refresh**: Tokens refreshed automatically before expiration\n- **Secure Cleanup**: Tokens removed from memory after use\n- **Input Validation**: All inputs validated and sanitized\n- **Migration**: File-based token storage with 600 permissions for secure credential management\n\n## 🧪 Testing\n\n```bash\n# Run tests\nnpm test\n\n# Test authentication\nnpm run setup -- --test\n\n# Validate configuration\nnpm run setup -- --validate\n```\n\n## 🐛 Troubleshooting\n\n### Authentication Issues\n\n**🎯 Automatic Authentication**: Claude automatically detects authentication issues and suggests the `salesforce_auth` tool. No manual troubleshooting needed!\n\n**Common Scenarios:**\n1. **First-time use**: Claude will automatically suggest authentication when you first try to use Salesforce tools\n2. **Token expiration**: When tokens expire, Claude detects this and prompts for re-authentication  \n3. **Invalid credentials**: Clear error messages guide you to fix configuration issues\n4. **Session expired**: Automatic detection with friendly prompts to re-authenticate\n\n### Token Security\n\n**🔒 Secure Token Storage**: Authentication tokens are stored securely in the local file system with strict permissions.\n\n**Security Features:**\n- **File Permissions**: Token files are created with `0600` permissions (readable/writable only by owner)\n- **Location**: Tokens stored in `cache/salesforce-tokens.json` (excluded from git)\n- **Automatic Security**: Permission verification and automatic fixing if needed\n- **No Network Exposure**: Tokens never leave your local machine\n- **File-based Security**: Secure token storage with strict file permissions for credential protection\n\n**Security Verification:**\n```bash\n# Check token file security\nls -la cache/salesforce-tokens.json\n# Should show: -rw------- (600 permissions)\n\n# Run security test\nnode test-token-security.js\n```\n\n**What this means:**\n- Other users on your system **cannot** read your Salesforce tokens\n- Only your user account has access to the authentication data\n- Prevents unauthorized access to your Salesforce organization\n- Complies with security best practices for credential storage\n\n### Quick Fix in Claude Desktop\nIf you get authentication errors, simply tell Claude:\n```\nAuthenticate with Salesforce\n```\nOr Claude will automatically suggest: `Use the salesforce_auth tool to authenticate with Salesforce`\n\n**✨ No more manual terminal setup!** Everything happens seamlessly through Claude Desktop.\n\n### Connection Issues\n\n1. **\"Cannot connect to Salesforce\"**: Verify your Instance URL\n2. **\"Insufficient permissions\"**: Check user permissions in Salesforce\n3. **\"CORS errors\"**: Ensure Connected App callback URL is correct\n\n### Common SOQL Errors\n\n1. **Field not found**: Use API names, not field labels\n2. **Object not found**: Check spelling and API name of objects\n3. **Syntax errors**: Ensure proper SOQL syntax with single quotes\n\n## 📚 Documentation\n\n- [OAuth Setup Guide](docs/oauth-guide.md) - Detailed Connected App configuration\n- [Setup Instructions](docs/setup.md) - Step-by-step setup process  \n- [Usage Examples](docs/examples.md) - Comprehensive usage examples\n- [Architecture Plan](mcp-salesforce-architecture.md) - Technical architecture details\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and test thoroughly\n4. Submit a pull request with detailed description\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- **Issues**: Report bugs and feature requests via GitHub Issues\n- **Documentation**: Check the `docs/` folder for detailed guides\n- **Community**: Join discussions in GitHub Discussions\n\n---\n\n**Made with ❤️ for the MCP ecosystem**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAiondaDotCom%2Fmcp-salesforce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAiondaDotCom%2Fmcp-salesforce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAiondaDotCom%2Fmcp-salesforce/lists"}