Salesforce

@mindstone/mcp-server-salesforce

[npm version] [License: FSL-1.1-MIT]

Salesforce CRM MCP server — accounts, contacts, opportunities, leads, tasks, users, and custom objects via the Salesforce API.

Best when an MCP host needs a local, install-and-run CRM connector for everyday sales work rather than a Salesforce-hosted endpoint.

Status

• Version: 0.2.6 · npm
• Auth: OAuth (local 127.0.0.1 callback) or static access token (SALESFORCE_CLIENT_SECRET, SALESFORCE_ACCESS_TOKEN)
• Tools: 37 (accounts, contacts, opportunities, leads, tasks, cases, events, search, notes, campaigns, reports, query)
• Surface: cloud-api
• Machine-readable: STATUS.json

Why this exists

Salesforce's own MCP options are the right starting point for many teams. This package is for teams that want a normal npm MCP server they can run locally in any stdio host.

It gives an assistant focused access to the CRM work people actually ask for: finding accounts and contacts, updating leads, creating opportunities and tasks, running CRM searches, and working with custom objects. The benefit is a short path from a natural-language sales request to the right Salesforce records, with write actions kept visible to the host.

Example interaction

"Find Acme Corp in Salesforce, create a Q3 expansion opportunity for $75,000, and add a follow-up task for next Friday."

Tools the host calls:

1. salesforce_get_accounts — searches accounts by name and returns the matching account ID.
2. salesforce_create_opportunity — creates the opportunity against that account.
3. salesforce_create_task — adds a follow-up task related to the new opportunity.

Response (trimmed):

{  "account": { "id": "001xx000003DGbYAAW", "name": "Acme Corp" },  "opportunity": {    "id": "006xx000004TmiYAAS",    "name": "Q3 expansion",    "amount": 75000,    "stage": "Prospecting"  },  "task": {    "id": "00Txx000006rYxDEAU",    "subject": "Follow up on Q3 expansion"  }}

Requirements

• Node.js 20+
• npm
• A Salesforce Connected App for the OAuth path, or a valid access token plus instance URL for manual-token mode.

One-click install

[Add to Cursor] [Add to VS Code] [Add to VS Code Insiders]

After clicking the button, your host will prompt you to fill: SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET, SALESFORCE_ACCESS_TOKEN, SALESFORCE_CONFIG_DIR, SALESFORCE_OAUTH_PORT.

{  "mcpServers": {    "Salesforce": {      "command": "npx",      "args": [        "-y",        "@mindstone/mcp-server-salesforce"      ],      "env": {        "SALESFORCE_CLIENT_ID": "",        "SALESFORCE_CLIENT_SECRET": "",        "SALESFORCE_ACCESS_TOKEN": "",        "SALESFORCE_CONFIG_DIR": "~/.mcp/salesforce",        "SALESFORCE_OAUTH_PORT": "0"      }    }  }}

Quick Start

Install & build

cd <path-to-repo>/connectors/salesforcenpm installnpm run build

npx

npx -y @mindstone/mcp-server-salesforce

Local

node dist/index.js

Configuration

OAuth (Recommended)

Set these environment variables:

• SALESFORCE_CLIENT_ID — Your Salesforce Connected App client ID
• SALESFORCE_CLIENT_SECRET — Your Salesforce Connected App client secret
• SALESFORCE_SANDBOX — Set to "true" for sandbox environments (optional)

Then call salesforce_connect_account to start the OAuth flow.

Manual Token

• SALESFORCE_ACCESS_TOKEN — A valid Salesforce access token
• SALESFORCE_INSTANCE_URL — Your Salesforce instance URL (e.g., https://mycompany.my.salesforce.com)

Additional Options

• SALESFORCE_CONFIG_DIR — Custom config directory (default: ~/.mcp/salesforce)
• SALESFORCE_OAUTH_PORT — OAuth callback port (0 = OS-assigned; default: 0)
• SALESFORCE_OAUTH_SCOPES — Space-separated OAuth scopes. Leave unset to use the connector default.

Available Tools (37)

Account Management

• salesforce_connect_account — Connect a Salesforce account via OAuth
• salesforce_list_connected_accounts — List connected accounts
• salesforce_disconnect_account — Disconnect an account

CRM Accounts

• salesforce_get_accounts — Get CRM accounts with filters
• salesforce_create_account — Create a CRM account
• salesforce_update_account — Update a CRM account

Contacts

• salesforce_get_contacts — Get contacts with filters
• salesforce_create_contact — Create a contact
• salesforce_update_contact — Update a contact

Opportunities

• salesforce_get_opportunities — Get opportunities with filters
• salesforce_create_opportunity — Create an opportunity
• salesforce_update_opportunity — Update an opportunity

Leads

• salesforce_get_leads — Get leads with filters
• salesforce_create_lead — Create a lead
• salesforce_convert_lead — Convert a lead to Account + Contact
• salesforce_update_lead — Update a lead

Tasks

• salesforce_get_tasks — Get tasks with filters
• salesforce_create_task — Create a task
• salesforce_update_task — Update a task

Cases

• salesforce_get_cases — Get support cases with filters
• salesforce_create_case — Create a support case
• salesforce_update_case — Update a support case

Events

• salesforce_get_events — Get calendar events with filters
• salesforce_create_event — Create a calendar event

Search

• salesforce_search — Cross-object full-text search (SOSL); the response's truncated flag tells you whether more matches exist beyond the limit

Notes

• salesforce_get_notes — Get notes attached to a record
• salesforce_create_note — Create a note, optionally attached to a record (a failed attach rolls the note back, or reports the orphaned note ID)

Campaigns

• salesforce_get_campaigns — Get marketing campaigns with filters
• salesforce_get_campaign_members — Get leads/contacts in a campaign

Reports

• salesforce_run_report — Run an existing Salesforce report (Analytics REST API)

Users

• salesforce_get_users — Get Salesforce users

Query & Schema

• salesforce_query — Execute raw SOQL queries
• salesforce_describe_object — Get object metadata and fields
• salesforce_list_objects — List available Salesforce objects

Generic CRUD

• salesforce_create_record — Create any Salesforce record
• salesforce_update_record — Update any Salesforce record
• salesforce_get_records — Query any Salesforce object

Security notes

• The standalone OAuth callback server binds to 127.0.0.1; it does not honour environment overrides that would expose the callback beyond loopback.
• OAuth credentials are stored under SALESFORCE_CONFIG_DIR (default ~/.mcp/salesforce) with restrictive directory and file permissions.
• Write and disconnect tools are marked so capable hosts can ask for confirmation before changing Salesforce data.
• SOQL helper paths escape backslashes and apostrophes. Filters treat % and _ literally, including the LIKE operator in salesforce_get_records. SOSL searches escape reserved characters, including apostrophes. In salesforce_get_records, dates (2026-01-31), datetimes with a time zone (2026-01-31T09:00:00Z) and JSON null are sent unquoted: use dates for date fields and datetimes for datetime fields such as CreatedDate. Use JSON null, not the string "null", with = or != to match empty fields. For text that looks like a date, use salesforce_query.
• Raw SOQL queries strip comments without changing string literals and cap row or grouped results at 200. Ungrouped aggregates receive no generated LIMIT: an explicit COUNT() limit is preserved to bound the count, while limits on other ungrouped aggregates are removed because Salesforce rejects them. FOR VIEW and FOR REFERENCE stay after LIMIT and OFFSET.
• Read fields and generic filter fields accept relationship paths such as Owner.Name; write field keys must be single API names.
• Session expiry is recognized by Salesforce's error code as well as its message. A refused expired or revoked refresh token asks you to reconnect and clears the cached connection, leaving the token file unchanged. A failed save of a renewed sign-in returns TOKEN_SAVE_FAILED without running the request; saving is retried on the next call. If that save still fails, the failure is logged and the request runs, but a restart may require reconnecting. Invalid field, invalid object and malformed query errors include recovery hints; vendor messages remain wrapped as untrusted content. When Salesforce refuses a field, the error can also include field_suggestions: up to three real field names from that object. These are possible matches, not confirmed replacements, because the field may be hidden from this user.
• salesforce_get_notes reads up to 150 linked documents before fetching the linked notes, returns an empty result when no links exist, and adds truncated: true when it reaches 150, because linked files use up that allowance and notes may be missing. The note result limit remains 200 (default 50).
• Record text returned by read tools is wrapped in <untrusted-content> envelopes so Salesforce-authored field values are presented to the model as data, not instructions.
• salesforce_convert_lead reports a conversion as failed when Salesforce rejects it at the record level (e.g. a validation rule), instead of claiming success; the org-authored error detail is enveloped the same way.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.