Salesforce Integration via Model Context Protocol (MCP)

This repository furnishes an MCP service implementation dedicated to seamless integration with Salesforce organizations. It furnishes capabilities to execute arbitrary SOQL inquiries, fetch schema metadata, and manage persistent Salesforce records through a standardized communication interface.

Core Capabilities

• Establish secure connectivity to Salesforce tenants leveraging configuration variables.
• Dispatch and process custom SOQL statements against Salesforce datasets.
• Obtain and interpret Salesforce entity structure and associated metadata.
• Catalog and manage declarative automation artifacts, such as Salesforce Flows.
• Secure handling of authentication credentials via environment variables.

Essential Prerequisites

• Node.js runtime environment (version 14 or newer is required).
• Node Package Manager (npm) utility.
• Access credentials for a target Salesforce organization with requisite API permissions.
• Necessary Salesforce login particulars (user identifier and access token/password).

Deployment Instructions

1. Obtain the source code by cloning the repository: git clone <repository-url> cd <repository-directory>

2. Install required software packages: npm install

3. Establish a configuration file named .env in the project root containing Salesforce connection specifics and the target API revision: SF_LOGIN_URL=https://your-instance.salesforce.com/ SF_USERNAME=your_username SF_PASSWORD=your_password SF_API_VERSION=58.0

4. For testing or sandbox access, substitute the login URL with https://test.salesforce.com/.

5. The SF_API_VERSION dictates the version utilized for all API interactions. Adjust this value according to your organizational standards.

Operational Guide

Initiating the MCP Service Host

Launch the service listener process:

node server.js

The service will authenticate with Salesforce using the parameters defined in .env and commence awaiting incoming MCP directives.

Submitting SOQL Data Retrieval Requests

Once active, SOQL queries can be dispatched through the MCP interface. The service exposes a dedicated soqlQuery tool designed to accept SOQL strings and return the resultant dataset.

Illustrative SOQL operation:

SELECT Id, Name, Status FROM Account LIMIT 5

Retrieving Salesforce Flow Definitions

To obtain a catalogue of all declarative Flows within your organization, employ the retrieveMetadata tool, specifying the metadata type as Flow. This action yields the definitions and structural details for all discovered flows.

Configuration within Cursor IDE

To integrate this Salesforce MCP host with the Cursor development environment, augment your local mcp.json definition with the subsequent block:

"mcpServers": {
  "mcp-salesforce": {
    "command": "node /absolute/path/to/your/project/root/server.js",
    "transport": "stdio",
    "args": []
  }
}

• Substitute /absolute/path/to/your/project/root/server.js with the full system path pointing to your server.js entry point.
• Ensure the service is launched from the repository's root directory to guarantee successful loading of environment variables and dependencies.

Upon configuration update in mcp.json, connectivity to the Salesforce MCP host is established within Cursor, unlocking all associated functionalities.

Directory Layout

• server.js - Primary execution script for the MCP host and Salesforce authentication bootstrap.
• tools.js - Module containing all defined MCP tool functions (e.g., SOQL execution, metadata fetching).
• .env - Configuration file for sensitive credentials and operational parameters.
• package.json - Manifest detailing project dependencies and execution scripts.

Security Best Practices

• Crucially: Never commit the .env file to any managed source control repository.
• Ensure .env is explicitly listed in your .gitignore file.
• Rely exclusively on environment variables for all confidential parameters.
• For production deployments, investigate employing more robust credential management mechanisms beyond simple password authentication.

Diagnostic Guidance

Connection Failure Analysis

If authentication or connection establishment proves unsuccessful: 1. Confirm the accuracy of Salesforce credentials within the .env configuration. 2. Validate that the target Salesforce instance is reachable over the network. 3. Check if the originating machine's IP address requires whitelisting within Salesforce security settings. 4. Verify the assigned Salesforce user possesses active API access privileges.

Query Execution Failures

If SOQL statements return errors: 1. Scrutinize the syntax of the submitted SOQL string for correctness. 2. Confirm the existence and spelling of referenced entities and fields within the target organization. 3. Verify that the authenticating user has the necessary object and field-level security permissions.

Licensing

MIT License

Contributions

We welcome external contributions! Please utilize the standard Pull Request workflow for submissions.