Salesforce MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless Salesforce integration for AI development tools like Claude Desktop, Cline, and other MCP-compatible clients.

🚀 Features

17 Comprehensive Tools

🔍 Query & Search Tools

• execute-soql - Execute SOQL queries with auto-bulk switching and pagination

• execute-sosl - Multi-object search with result aggregation

• describe-sobject - SObject metadata with intelligent caching

⚡ Apex Development Tools

• execute-apex - Anonymous Apex execution with debug log capture

• run-apex-tests - Apex test execution with coverage reporting

• get-apex-logs - Debug log retrieval with filtering

📊 Data Management Tools

• create-record - Single/bulk record creation with auto-bulk switching

• get-record - Record retrieval with field selection

• update-record - Single/bulk record updates with validation

• delete-record - Single/bulk record deletion

• upsert-record - External ID-based upsert operations

🔧 Metadata Tools (Component-Based)

• list-metadata-types - Discover metadata types

• deploy-metadata - Deploy individual metadata components (e.g., ApexClass, CustomObject) from files or JSON

• deploy-bundle - Deploy a metadata bundle (e.g., LWC) from a directory path

• retrieve-metadata - Retrieve individual metadata components, with an option to save to a file

• check-deploy-status - Check the status of a deployment

🔗 Connection Tools

• test-connection - Connection validation and health monitoring

Key Capabilities

• 🔄 Auto-Bulk Switching - Intelligent API selection for optimal performance

• 🔐 Dual Authentication - OAuth2 and Username/Password support

• ⚡ Smart Caching - 1-hour TTL for SObject metadata

• 🛡️ Type Safety - Full TypeScript implementation with runtime validation

• 📝 Comprehensive Logging - Detailed debugging and monitoring

• 🔍 Raw Error Exposure - Preserve exact Salesforce errors for debugging

🚀 Installation

To use with Desktop APP, such as Claude Desktop, Cline, Cursor, and so on, add the MCP server config below.

On macOS / Linux systems:

{
  "mcp.servers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "your-username@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "",
        "SF_LOGIN_URL": "https://login.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

{
  "mcp.servers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_CLIENT_ID": "your-oauth2-client-id",
        "SF_CLIENT_SECRET": "your-oauth2-client-secret",
        "SF_REFRESH_TOKEN": "your-refresh-token",
        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

On Windows systems:

{
  "mcp.servers": {
    "salesforce": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "your-username@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "",
        "SF_LOGIN_URL": "https://login.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

{
  "mcp.servers": {
    "salesforce": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_CLIENT_ID": "your-oauth2-client-id",
        "SF_CLIENT_SECRET": "your-oauth2-client-secret",
        "SF_REFRESH_TOKEN": "your-refresh-token",
        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

Configuration File Locations

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

⚠️ Important: After adding or modifying the MCP server configuration, you must restart VS Code for the changes to take effect.

• Windows: %USERPROFILE%\.cursor\mcp.json

• macOS: ~/.cursor/mcp.json

• Linux: ~/.cursor/mcp.json

Tool Safety Levels

✅ Safe for Auto-Approval (alwaysAllow)

• test-connection - Connection validation (read-only)

• execute-soql - SOQL queries (read-only)

• describe-sobject - Metadata inspection (read-only)

• get-record - Single record retrieval (read-only)

• get-apex-logs - Debug log access (read-only)

• list-metadata-types - Metadata type discovery (read-only)

⚠️ Requires Manual Approval

• create-record, update-record, delete-record, upsert-record - Data modification

• deploy-metadata - Metadata deployment

• execute-apex, run-apex-tests - Code execution

• execute-sosl - Search operations (can be resource-intensive)

• retrieve-metadata - Metadata retrieval (can be large)

Authentication

Username/Password Authentication

1. Obtain your security token from Salesforce Setup → Personal Information → Reset Security Token (only required if your IP is not trusted)

2. Set environment variables as shown in the configuration section

3. Use https://login.salesforce.com for production or https://test.salesforce.com for sandboxes

💡 Security Token: Only add the security token if Salesforce requires it for your connection. If not leave SF_SECURITY_TOKEN empty.

OAuth2 Authentication

1. Create a Connected App in Salesforce Setup

2. Configure OAuth settings and obtain client credentials

3. Generate a refresh token using the OAuth2 flow

4. Set environment variables as shown in the configuration section

🏗️ Architecture

Core Components

• Authentication Manager - Dual OAuth2/Username-Password support

• Connection Manager - Singleton pattern with health monitoring

• Tool Classes - Organized by functionality (Query, Apex, Data, Metadata)

• Error Handler - Comprehensive error formatting with context

• Cache Manager - TTL-based caching for performance optimization

Performance Features

• Auto-Bulk Switching - Automatically uses Bulk API for large operations

• Intelligent Caching - SObject metadata cached for 1 hour

• Connection Reuse - Single connection across all operations

• Polling Optimization - Efficient monitoring of long-running operations

🧪 Testing

# Test individual tools
node tests/test-query-tools.js
node tests/test-data-tools.js
node tests/test-apex-tools.js
node tests/test-metadata-tools.js

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

🔗 Related Projects

• Model Context Protocol - The protocol this server implements

• jsforce - Salesforce API library used in this project

• Claude Desktop - AI assistant that supports MCP servers

• Cline - VS Code extension for AI-assisted development

👨‍💻 Author

Jarosław Jaworski

🤖 Development Credits

Part of this implementation was developed with assistance from Claude Sonnet 4 using the Cline VS Code extension, demonstrating the power of AI-assisted development in creating comprehensive developer tools.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.