Salesforce MCP Server

How to use

You interact with this Salesforce MCP server by starting it as a local process and then configuring your MCP client to connect to it. The server exposes tools to run SOQL queries and to perform CRUD operations on Leads. You will authenticate with Salesforce using the OAuth 2.0 password grant flow, obtain an access token, and then issue requests through the provided endpoints.

Typical usage patterns include: 1) Running a SOQL query to fetch contact or lead data, 2) Creating a new Lead with required fields, 3) Reading, updating, or deleting an existing Lead by its Salesforce ID. Ensure you provide the required fields for create and update operations and supply the Lead ID for get, update, or delete actions.

How to install

Prerequisites you need before installation: Python 3.14 or newer, a Salesforce account with API access, and OAuth credentials (Client ID and Client Secret). You will also use a local runtime tool to start the MCP server.

Step 1: Clone the project repository.

git clone <repository-url>
cd salesforceMCP

Step 2: Install dependencies using the recommended runtime. You will start the server in development mode with the provided runtime tool.

uv sync

Step 3: Create a .env file in the project root with your Salesforce credentials.

URL=your-instance.my.salesforce.com
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
USERNAME=your_username
PASSWORD=your_password

MCP client configuration and running the server

Configure your MCP client to connect to the local Salesforce MCP server. The following examples show how to wire the server into Claude Desktop and Cursor using the runtime runner. Replace the absolute path to the project directory and fill in your Salesforce credentials.

{
  "mcpServers": {
    "salesforce": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/salesforceMCP",
        "run",
        "main.py"
      ],
      "env": {
        "URL": "your-instance.my.salesforce.com",
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "USERNAME": "your_username",
        "PASSWORD": "your_password"
      }
    }
  }
}

For Cursor, use the same configuration shape and place it in your MCP settings file.

{
  "mcpServers": {
    "salesforce": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/salesforceMCP",
        "run",
        "main.py"
      ],
      "env": {
        "URL": "your-instance.my.salesforce.com",
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret",
        "USERNAME": "your_username",
        "PASSWORD": "your_password"
      }
    }
  }
}

Additional configuration and security notes

Important considerations: do not commit the .env file to version control and protect OAuth credentials. Use environment variables for sensitive configuration and validate domain names before making requests.

Error handling is built into the server with logging to stderr, including timestamps and severity levels, to help you diagnose issues with authentication or API requests.

Authentication and security

The server uses OAuth 2.0 password grant flow for authentication. Each request to Salesforce goes through the following steps: 1) Authenticate with credentials from your .env file, 2) Obtain an access token, 3) Use the token for API requests.

Development and testing

Run tests with the following command to ensure the MCP server behaves as expected.

pytest

View test coverage by running this command.

pytest --cov=src --cov-report=html

Notes on dependencies and licensing

This MCP server depends on the FastMCP framework, the Model Context Protocol, and common HTTP and testing libraries. Ensure you have Python installed and access to the Salesforce API.

run_soql

Execute SOQL queries to fetch data from Salesforce within the MCP server.

run_lead_operation

Perform CRUD operations on Salesforce Lead objects, including create, read, update, delete, and get by ID.