Salesforce MCP Server

An MCP (Model Context Protocol) server implementation for Salesforce integration, enabling AI assistants to interact with Salesforce data through standardized tools.

Features

This MCP server provides three powerful tools for Salesforce integration:

• list_objects: List all available Salesforce objects with their metadata
• describe_object: Get detailed field information for a specific Salesforce object
• execute_soql_query: Execute SOQL queries against your Salesforce instance

Prerequisites

• Python 3.13+
• A Salesforce account with API access
• Salesforce security token (see setup instructions below)

Installation

1. Clone this repository:

git clone <repository-url>
cd mcp-salesforce

2. Create and activate a virtual environment using uv:

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows

3. Install dependencies:

uv pip install -e .

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and add your Salesforce credentials:

SALESFORCE_USERNAME=your_username@example.com
SALESFORCE_PASSWORD=your_password
SALESFORCE_SECURITY_TOKEN=your_security_token

Getting Your Salesforce Security Token

1. Log in to Salesforce
2. Go to Setup > Personal Setup > My Personal Information > Reset My Security Token
3. Click Reset Security Token
4. Check your email for the new security token

Usage

Running the Server

Start the MCP server using one of the following methods:

# Method 1: Run directly with Python
python main.py

# Method 2: Use the installed command
mcp-salesforce

# Method 3: Run with uv (recommended)
uv run mcp-salesforce

Testing with MCP Inspector

The MCP Inspector is a powerful tool for testing and debugging your MCP server. It provides an interactive interface to explore available tools and test them with different parameters.

Method 1: Using uv run with mcp-salesforce command (recommended)

npx @modelcontextprotocol/inspector uv run mcp-salesforce

Method 2: Using uv run with Python directly

npx @modelcontextprotocol/inspector uv run python main.py

This will:

1. Start the MCP Inspector web interface
2. Launch your Salesforce MCP server
3. Open a browser window where you can:
   • View all available tools
   • Test each tool with custom parameters
   • See the JSON responses
   • Debug any issues

Note: Make sure your .env file is configured with valid Salesforce credentials before running the inspector.

Available Tools

1. list_objects

Lists all available Salesforce objects in your org.

Returns:

• Dictionary containing:
  • objects: Array of object metadata, each with:
    • name: API name of the object
    • label: Display label
    • custom: Whether it's a custom object
    • queryable: Whether it can be queried via SOQL
    • searchable: Whether it's searchable
    • createable: Whether new records can be created
    • updateable: Whether records can be updated
    • deletable: Whether records can be deleted

2. describe_object

Get all fields for a specific Salesforce object.

Parameters:

• object_name (string): The API name of the Salesforce object (e.g., 'Account', 'Contact', 'CustomObject__c')

Returns:

• Dictionary containing:
  • name: Object API name
  • fields: Array of field definitions with:
    • name: Field API name
    • label: Field display label
    • type: Data type (string, number, date, picklist, etc.)
    • length, precision, scale: Size constraints
    • required: Whether the field is required
    • unique: Whether values must be unique
    • createable, updateable: Field permissions
    • calculated: Whether it's a formula field
    • defaultValue: Default value for the field
    • picklistValues: Available values (for picklist fields)
    • referenceTo: Referenced object (for lookup/master-detail fields)

3. execute_soql_query

Execute SOQL (Salesforce Object Query Language) queries.

Parameters:

• query (string): The SOQL query string (e.g., 'SELECT Id, Name FROM Account LIMIT 10')

Returns:

• Dictionary containing:
  • query: The executed SOQL query string
  • rows: Array of records with queried fields
  • row_count: Total number of records returned
  • columns: Array of column names in the result set

Important SOQL Rules:

1. CANNOT use SELECT * - You MUST specify column names explicitly
2. Aggregate queries CANNOT use LIMIT - Queries using COUNT, SUM, AVG, MIN, MAX cannot have LIMIT clause

Example Queries:

-- Get first 10 accounts
SELECT Id, Name, Industry FROM Account LIMIT 10

-- Get contacts with filters
SELECT Id, FirstName, LastName, Email FROM Contact WHERE Email != null LIMIT 20

-- Join query (using relationship)
SELECT Id, Name, Owner.Name FROM Account WHERE CreatedDate = TODAY

Development

Project Structure

mcp-salesforce/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── .env.example         # Example environment variables
├── .env                 # Your actual credentials (git-ignored)
└── README.md           # This file

Dependencies

• fastmcp: Framework for building MCP servers
• simple-salesforce: Python client for Salesforce REST API
• python-dotenv: Load environment variables from .env files

Adding to Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "salesforce": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-salesforce",
        "run",
        "mcp-salesforce"
      ]
    }
  }
}

Replace /absolute/path/to/mcp-salesforce with the actual path to your project directory.

Alternative configuration using Python directly:

{
  "mcpServers": {
    "salesforce": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-salesforce",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Error Handling

The server includes comprehensive error handling:

• Missing Credentials: Clear error message if environment variables are not set
• Authentication Errors: Salesforce API authentication failures are reported
• Invalid Queries: SOQL syntax errors are returned with helpful messages
• API Limits: Respects Salesforce API rate limits

Security Notes

• Never commit your .env file to version control
• Keep your Salesforce security token secure
• Consider using OAuth 2.0 for production deployments
• Regularly rotate your security token

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Support

For issues and questions:

• Check the simple-salesforce documentation
• Review Salesforce API documentation
• Open an issue in this repository