Salesforce MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Salesforce CRM through its REST API. This server enables AI assistants to query data using SOQL and perform CRUD operations on Salesforce objects like Leads.

Features

• SOQL Query Execution: Run Salesforce Object Query Language (SOQL) queries to fetch data from your Salesforce org

• Lead Management: Complete CRUD operations (Create, Read, Update, Delete) for Salesforce Lead objects

• OAuth Authentication: Secure authentication using OAuth 2.0 password grant flow

• Custom Field Support: Handle both standard and custom Salesforce fields

Prerequisites

• Python >= 3.14

• Salesforce account with API access

• OAuth credentials (Client ID and Client Secret)

Installation

1. Clone the repository:

2. Install dependencies using uv (recommended) or pip:

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

Configuration

To use this MCP server with Claude Desktop or Cursor, you need to configure it in your MCP settings file.

Claude Desktop

Add the following to your Claude Desktop configuration file:

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

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

Cursor

Add the following to your Cursor MCP settings file (~/.cursor/mcp.json or similar):

Important: Replace /absolute/path/to/salesforceMCP with the actual absolute path to your project directory, and fill in your Salesforce credentials.

After adding the configuration, restart Claude Desktop or Cursor for the changes to take effect.

Available Tools

1. run_soql

Execute SOQL queries to fetch data from Salesforce.

Parameters:

• query (str): The SOQL query to execute

Example:

Note: Custom objects and fields in Salesforce end with __c

2. run_lead_operation

Perform CRUD operations on Salesforce Lead objects.

Operations:

• create: Create a new Lead (requires LastName and Company)

• update: Update an existing Lead (requires lead_id)

• delete: Delete a Lead (requires lead_id)

• get: Fetch a Lead by ID (requires lead_id)

Standard Fields:

• lead_id: Salesforce Lead ID (required for update, delete, get)

• last_name: Lead's last name (required for create)

• company: Lead's company (required for create)

• first_name: Lead's first name

• salutation: Salutation (e.g., 'Mr.', 'Ms.', 'Dr.')

• title: Job title

• email: Email address

• phone: Phone number

• mobile_phone: Mobile phone number

• fax: Fax number

• website: Website URL

• lead_source: Lead source (e.g., 'Web', 'Phone Inquiry')

• status: Lead status (e.g., 'Open', 'Contacted', 'Qualified')

• rating: Lead rating (e.g., 'Hot', 'Warm', 'Cold')

• industry: Industry

• annual_revenue: Annual revenue (float)

• number_of_employees: Number of employees (int)

• street: Street address

• city: City

• state: State/Province

• postal_code: Postal/ZIP code

• country: Country

• description: Notes about the lead

• owner_id: Salesforce User ID of lead owner

• is_converted: Whether the lead has been converted (bool)

• custom_fields: Dictionary of custom fields (e.g., {"My_Field__c": "value"})

Project Structure

Development

Running Tests

Test Coverage

Authentication

This server uses OAuth 2.0 password grant flow for authentication. Each request to Salesforce will:

1. Authenticate using the credentials from your .env file

2. Obtain an access token

3. Use the token for API requests

Error Handling

The server includes comprehensive error logging. Errors are logged to stderr with timestamps and severity levels.

Dependencies

• fastmcp>=2.14.1 - FastMCP framework for building MCP servers

• mcp[cli]>=1.25.0 - Model Context Protocol implementation

• requests>=2.32.5 - HTTP library for API requests

• pytest>=9.0.2 - Testing framework

• pytest-cov>=7.0.0 - Test coverage plugin

• pytest-mock>=3.15.1 - Mocking plugin for pytest

Security Notes

• Never commit your .env file to version control

• Keep your OAuth credentials secure

• Use environment variables for sensitive configuration

• Validate domain names before making requests

License

[Add your license information here]

Contributing

[Add contribution guidelines here]