salesforce-mcp

A small MCP server that lets an AI agent read a Salesforce pipeline and write back to it — safely.

What it does

Give an LLM tool access to your Salesforce org and it can answer "what's in my pipeline," "what's gone quiet," or "log that I called Acme today" directly from a chat interface, instead of you tabbing over to Salesforce. This server is the bridge: it exposes a handful of MCP tools that wrap the Salesforce REST API.

Read tools — open-ended, SOQL-backed:

Tool	What it returns
list_open_opportunities	Open deals, earliest close first
get_opportunity	One Opportunity by Id
search_opportunities	Fuzzy match by deal or account name
get_pipeline_summary	Total value, deal count, stage breakdown
list_accounts	Accessible Accounts
list_contacts	Contacts, optionally scoped to an Account
whoami	Confirms the connection and identity

Write tools — deliberately narrow:

Tool	What it can do	What it structurally cannot do
log_activity	Create a Task or Event	Create anything else
update_opportunity	Set StageName, NextStep, CloseDate, Amount	Touch any other field or object

Why the write surface is this narrow

Handing an LLM a Salesforce API key is handing it delete access to a company's revenue data. The usual mitigation is a system prompt telling the model to "only update these fields" — which is a suggestion, not a boundary, and every prompt-injection writeup of the last two years is a demonstration of what happens to suggestions.

This server draws the boundary in code instead. update_opportunity takes a fields dict, diffs its keys against a four-item allowlist, and refuses the entire call — before a single HTTP request is built — if anything outside that set is present. log_activity calls the client's create() with a hardcoded sobject name; there is no tool exposed to the model that takes an arbitrary sobject and payload and creates it. An LLM driving this server cannot delete a record, cannot create an Account or Contact, and cannot write an unauthorized field — not because it was told not to, but because those code paths don't exist. See tests/test_server_write_guards.py for the guardrail tests, including the mixed-payload case (one bad field in an otherwise-valid update refuses the whole write, so a partial-apply can never silently drop part of the caller's intent).

SOQL injection gets the same treatment as the write surface: every Salesforce Id that reaches a query is validated against Salesforce's own 15/18-character Id format first (guards.validate_record_id), and every piece of free text is escaped per SOQL's quoted-string rules (guards.escape_soql_literal / escape_soql_like) rather than trusted. See tests/test_guards.py, including an explicit ' OR '1'='1 injection-attempt case.

Setup

1. Create a Connected App in your Salesforce org (Setup → App Manager → New Connected App), enable OAuth, and note the consumer key/secret.

2. Get a refresh token once, via the standard OAuth web-server flow against that Connected App — Salesforce's own Connected App walkthrough covers this in a few steps. You only do this once; the server exchanges the refresh token for short-lived access tokens on every run.

3. Configure: copy .env.example to .env and fill in SF_CLIENT_ID, SF_CLIENT_SECRET, SF_REFRESH_TOKEN (and SF_LOGIN_BASE_URL if you're pointed at a sandbox).

4. Install and run:

   pip install -e ".[dev]"
   python -m salesforce_mcp.server
   

   Or point any MCP client (Claude Desktop, etc.) at salesforce-mcp as the command.

Testing

pip install -e ".[dev]"
pytest

Tests run entirely offline — test_salesforce_client.py uses httpx.MockTransport to simulate the Salesforce REST API (auth, pagination, rate limits, error responses), and test_server_write_guards.py substitutes a fake client to verify the allowlist logic fires before any request would be built. No live org or network access is required to run the suite.

What this deliberately is not

This is a clean-room extraction of one capability — read/write access to a Salesforce pipeline — built to be a self-contained, readable example of that pattern. It is not a general-purpose Salesforce SDK, does not implement the Bulk or Streaming APIs, and does not include any of the agent orchestration, evaluation harness, or product logic it was extracted alongside. What you're looking at is the whole repo.

License

MIT — see LICENSE.