simple-salesforce-mcp

A lightweight Salesforce MCP server. Talks straight to the Salesforce REST API over stdio with two runtime dependencies (mcp, httpx) — built as a fast-cold-start replacement for the official @salesforce/mcp DX server, whose dependency tree is too heavy for sandboxed environments.

Tools

Every tool carries MCP annotations (readOnlyHint / destructiveHint / idempotentHint). update_record and delete_record refuse to act unless the call includes confirm: true, and the refusal message instructs the model to present the exact change to the user and get approval first. SOQL itself cannot modify data, so the escape hatch stays read-only.

Authentication

The server performs no OAuth flow itself; it consumes an existing access token, resolved on every tool call (so an external process may rotate the token at any time):

1. Salesforce CLI auth store under $HOME:

   • ~/.sf/config.json → {"target-org": "<username>"} (or legacy ~/.sfdx/sfdx-config.json → {"defaultusername": ...})

   • ~/.sfdx/<username>.json → {"accessToken": "...", "instanceUrl": "https://..."}

   This is the shape written by sf org login, and the shape the JustParent platform materialises into sandboxes (with the platform refreshing the access token before each call). Refresh tokens and client secrets in these files are ignored — never read into memory, stored, or logged.

2. Environment variables (fallback, for local/standalone use): SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL.

On a rejected token (HTTP 401 / INVALID_SESSION_ID) the server re-reads the auth store once and retries, then reports that the connection needs to be re-established.

The REST API version defaults to 62.0; override with SALESFORCE_API_VERSION.

Running

# Standalone with env vars (get a token via: sf org display --json)
SALESFORCE_ACCESS_TOKEN=... \
SALESFORCE_INSTANCE_URL=https://yourorg.my.salesforce.com \
uvx --from git+https://github.com/JustParent/simple-salesforce-mcp simple-salesforce-mcp

Claude Desktop / generic MCP client config:

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JustParent/simple-salesforce-mcp", "simple-salesforce-mcp"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "...",
        "SALESFORCE_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      }
    }
  }
}

Smoke test (no network, prints version, credential status, and tools; exits 0):

uvx --from . simple-salesforce-mcp --test

Development

uv run pytest                    # unit tests, no network needed
uv run ruff check .              # lint
uv run ruff format .             # format (--check to verify only)
uv run mypy                      # type check (src and tests)
uv run simple-salesforce-mcp --test
npx @modelcontextprotocol/inspector uv run simple-salesforce-mcp   # interactive

CI (.github/workflows/tests.yml) runs on every push and pull request: the test suite on Python 3.10–3.13, ruff lint and format checks plus mypy, and a packaging job that installs the package the way sandboxes do (uvx --from .) to catch packaging breakage.

Security notes

• Access-token only: the server never requests, reads, or persists refresh tokens.

• Destructive operations (update/delete) are gated behind an explicit confirm=true argument with model-facing guidance to obtain user approval first.

• SOQL pagination cursors (next_url) are validated to be /services/data/... paths, and object/record identifiers are validated before being placed in URLs.

• Responses are size-capped with explicit truncation notices.