Skip to main content
Glama
Salesforce MCP Server

Salesforce MCP Server

by aiyanbo

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

Related MCP server: MCP Salesforce Server

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
  1. Create and activate a virtual environment using uv:

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows
  1. Install dependencies:

uv pip install -e .

Configuration

  1. Copy the example environment file:

cp .env.example .env
  1. 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:

Available Tools

4 tools
describe_objectA

Get all fields for a specific Salesforce object.

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

Returns: Dictionary containing object name and list of field definitions.

Inputs: object_name (required). Returns: object

execute_soql_queryA

Execute a SOQL query against Salesforce.

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

Returns: Dictionary containing query, rows, row_count, and columns.

IMPORTANT: Before constructing SOQL queries, use the get_soql_help() tool to understand: - Basic SOQL syntax and structure - How to write WHERE clauses and filters - Relationship queries (child-to-parent and parent-to-child) - Aggregate functions and GROUP BY - Common patterns and best practices

Reference: https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_select.htm

Important SOQL Rules: 1. CANNOT use SELECT * - You MUST specify column names explicitly 2. Aggregate queries (using COUNT, SUM, AVG, etc.) CANNOT use LIMIT

Inputs: query (required). Returns: object

get_soql_helpA

Get comprehensive help documentation for SOQL (Salesforce Object Query Language).

Returns: Dictionary containing SOQL syntax guide, examples, best practices, and common patterns.

Reference: https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_sosl_intro.htm

Inputs: no named parameters. Returns: object

list_objectsA

List all available Salesforce objects.

Returns: List of dictionaries containing object metadata including name, label, whether it's custom, and other attributes.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct responsibility: listing objects, describing an object, providing SOQL help, and executing a query. There is no overlap in purpose or confusion about which tool to use.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (list_objects, describe_object, get_soql_help, execute_soql_query). This is uniform and predictable.

    Tool Count5/5

    Four tools is well within the ideal range and each tool serves a clear, non-redundant function. The count feels appropriate for the server's focused scope of metadata access and SOQL execution.

    Completeness2/5

    The server lacks any record-level CRUD operations (create, update, delete) or a direct 'get record' tool, which are expected from a Salesforce MCP server. While it covers schema discovery and querying, significant functional gaps remain for real-world automation.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to securely interact with Salesforce CRM data through SOQL queries, CRUD operations, and metadata exploration. Supports connecting to Salesforce objects like Accounts, Contacts, and Opportunities via OAuth 2.0 authentication.
      8
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to interact with Salesforce through a secure interface for performing CRUD operations, executing SOQL queries, and managing schema discovery. It features a smart learning system that analyzes custom objects and fields to provide intelligent assistance tailored to specific Salesforce configurations.
      14
      53 npm
      17
      BSD 2-Clause "Simplified"
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to interact with Salesforce organizations, allowing them to execute Apex code, query data, describe objects, and manage org connections through natural language.
      47
      641 npm
      38
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to securely query, search, and modify Salesforce data through standard Salesforce APIs, including record CRUD, SOQL/SOSL search, Bulk API 2.0 operations, composite calls, object discovery, and custom Apex REST endpoints.
      15
      MIT