salesforce-mcp-jsforce

A lite, single-org Model Context Protocol server for Salesforce, built on jsforce.

• Bring your own token. The server never stores a client secret, username, or password. You authenticate once with OAuth; it holds only an access token + instance URL.
• Two ways to run. Locally over stdio (for Claude Code and other MCP clients) or as a dedicated streamable-HTTP server where each request carries its own token.
• Safe to host & open-source. No org-specific config, no multi-environment credential matrix, no destructive metadata tooling. Optional read-only mode.

Tools

| Tool | Mode | Description | | --- | --- | --- | | salesforce_identity | read | Identity of the supplied token (token validity check) | | salesforce_query | read | Run a SOQL query | | salesforce_search | read | Run a SOSL full-text search | | salesforce_list_objects | read | List sObjects + key metadata | | salesforce_describe_object | read | Trimmed describe of an sObject | | salesforce_get_record | read | Retrieve a record by Id | | salesforce_create_record | write | Create a record | | salesforce_update_record | write | Update a record | | salesforce_delete_record | write | Delete a record |

Set SF_READONLY=1 to register the read tools only.

Quick start

npm install -g @imazhar101/salesforce-mcp-jsforce

# 1. Log in (PKCE against your External Client App)
salesforce-mcp-jsforce login --client-id <ECA_CONSUMER_KEY>
#   sandbox: add --login-url https://test.salesforce.com

# 2. Use it from Claude Code
claude mcp add salesforce -- npx -y @imazhar101/salesforce-mcp-jsforce

login opens a browser, completes the OAuth handshake, saves the token to ~/.config/salesforce-mcp-jsforce/token.json, and prints ready-to-paste config.

Credentials

stdio — one of:

• SF_ACCESS_TOKEN + SF_INSTANCE_URL environment variables, or
• the token file written by login (read automatically).

HTTP — per request, via headers:

• X-SF-Access-Token
• X-SF-Instance-Url
• X-SF-Api-Version (optional)

Run as a dedicated HTTP server

PORT=3000 salesforce-mcp-jsforce http

Stateless streamable-HTTP at POST /mcp; health probe at GET /health. Each request is handled by a throwaway server instance keyed to its own token — no caller state is shared. Put it behind TLS; the access token is a live credential.

curl -s http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "X-SF-Access-Token: $SF_ACCESS_TOKEN" \
  -H "X-SF-Instance-Url: $SF_INSTANCE_URL" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Environment variables

| Var | Default | Purpose | | --- | --- | --- | | SF_ACCESS_TOKEN | — | stdio access token | | SF_INSTANCE_URL | — | stdio instance URL | | SF_API_VERSION | 62.0 | REST API version | | SF_READONLY | off | 1 strips write tools | | SF_LOGIN_URL | https://login.salesforce.com | OAuth host (sandbox: test.salesforce.com) | | SF_CLIENT_ID | — | ECA consumer key for login | | SF_CLIENT_SECRET | — | only for confidential apps | | SF_SCOPE | api refresh_token | OAuth scopes | | PORT | 3000 | HTTP host port |

Security model

• The token grants exactly the permissions of the user who authorized it — the server adds no privilege.
• In HTTP mode no credentials are persisted; the token lives only for the duration of one request.
• In stdio mode the saved token file is written chmod 600.
• Tokens are never logged.

Build from source

npm install
npm run build
node dist/index.js --help

License

MIT