Salesforce Model Context Protocol Interface

This repository furnishes a standardized Model Context Protocol (MCP) endpoint specifically engineered for interacting with Salesforce organizations. It abstracts complex Salesforce API interactions, permitting execution of data retrieval via SOQL, metadata introspection, and record lifecycle management through a consistent interface.

Core Capabilities

• Establish secure connections to diverse Salesforce tenants using environment configurations.
• Execute structured query language (SOQL) operations against platform data.
• Retrieve and parse complex Salesforce schema definitions and record sets.
• Catalog and manage declarative automation components (e.g., Flows).
• Secure credential storage leveraged exclusively through environment variables.

Required Dependencies

Prior to deployment, ensure the following prerequisites are satisfied on your operational system:

• Runtime Environment: Node.js (version 14 or newer recommended)
• Package Manager: npm (Node Package Manager)
• Target System: Active Salesforce instance possessing necessary API access permissions.
• Authentication Material: Valid Salesforce user credentials (username and access key/password).

Setup Procedures

1. Source Acquisition: Obtain a local copy of the source code base:

git clone cd

1. Dependency Resolution: Install all requisite Node packages:

npm install

1. Configuration File Creation: Generate a .env file in the repository root to securely define connection parameters and the Salesforce API revision level:

SF_LOGIN_URL=https://your-instance.salesforce.com/ SF_USERNAME=your_username SF_PASSWORD=your_password SF_API_VERSION=60.0

Note on Sandboxes: For testing environments, substitute the SF_LOGIN_URL with https://test.salesforce.com/. API Versioning: Adjust SF_API_VERSION to match the required Salesforce API level for your organization.

Operational Guidelines

Activating the MCP Service Host

Initiate the server process using the Node runtime:

node server.js

The service will initialize, authenticate against Salesforce using the data from .env, and commence listening for incoming MCP communication packets.

Executing Data Queries (SOQL)

Once the host is operational, data extraction is performed by utilizing the exposed soqlQuery utility within the MCP context. This tool accepts a standard SOQL string as input and returns the materialized result set.

Illustrative SOQL statement: sql SELECT AccountId, Name, AnnualRevenue FROM Opportunity WHERE IsClosed = TRUE LIMIT 10

Metadata Introspection (Flows Example)

To acquire metadata regarding declarative automation assets such as Flows, invoke the retrieveMetadata utility, specifying the relevant metadata entity name (Flow):

mcp_call("mcp_salesforce", "retrieveMetadata", { type: "Flow" })

This action yields a comprehensive list and structure definitions for all accessible Flows within the connected tenant.

Integration within Cursor IDE

To enable Cursor to interface with this specific Salesforce service, incorporate the following definition into your global or project-specific mcp.json configuration file:

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

• Crucially, replace the placeholder path with the absolute location pointing to your server.js executable.
• Ensure the execution context (directory) permits the server process to correctly resolve the .env configuration file and its dependencies.

Upon successful configuration registration in mcp.json, Cursor will recognize and allow interaction with the Salesforce tooling endpoint.

File System Layout

• server.js: Primary executable, managing the MCP network socket and core Salesforce session bootstrapping.
• tools.js: Module housing the definitions for all exposed MCP functions (e.g., query execution, metadata fetching).
• .env: Sensitive configuration parameters (NEVER commit this file).
• package.json: Manifest detailing project dependencies and auxiliary scripts.

Security Posture

Adherence to these security guidelines is paramount when managing sensitive credentials:

• Exclude the .env file from all version control repositories (e.g., via .gitignore).
• Mandate the use of environment variables for transmitting secrets to the runtime process.
• For high-security production deployments, investigate token-based or OAuth authentication flows over simple username/password.

Common Diagnostic Procedures

Authentication/Connectivity Failures

If the service fails to establish a link to Salesforce: 1. Double-check the credentials and endpoint URL within the .env file for typographical errors. 2. Confirm network accessibility to the target Salesforce instance. 3. Validate that the connecting user profile possesses the requisite API access rights. 4. Review Network Access settings within Salesforce to ensure the connecting IP range is permitted.

SOQL Execution Failures

Troubleshoot query failures by checking: 1. The syntactic correctness of the submitted SOQL statement. 2. The existence of the referenced data entities (objects) and attributes (fields) within the target org schema. 3. User security permissions related to the specific objects/fields targeted by the query.

Licensing

This software is distributed under the terms of the MIT License.

Collaboration

We welcome external contributions! Please submit proposed enhancements or fixes via a standard Pull Request.