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:

Username/Password Authentication

{
  "mcp.servers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "[email protected]",
        "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"
      ]
    }
  }
}

OAuth 2.0 Authentication

{
  "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:

Username/Password Authentication

{
  "mcp.servers": {
    "salesforce": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/salesforce-mcp-server"
      ],
      "env": {
        "SF_USERNAME": "[email protected]",
        "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"
      ]
    }
  }
}

OAuth 2.0 Authentication

{
  "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

Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Cline (VS Code)

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.

Cursor

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

Obtain your security token from Salesforce Setup → Personal Information → Reset Security Token (only required if your IP is not trusted)
Set environment variables as shown in the configuration section
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

Create a Connected App in Salesforce Setup
Configure OAuth settings and obtain client credentials
Generate a refresh token using the OAuth2 flow
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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.