Skip to main content
Glama
Salesforce MCP Server

Salesforce MCP Server

by hypn4

Salesforce MCP Server

Release Container

A Model Context Protocol (MCP) server that provides Salesforce integration for AI agents with flexible OAuth authentication.

Features

  • Dual OAuth modes - Bearer token validation or full OAuth 2.1 proxy

  • 16 MCP tools across 4 categories for comprehensive Salesforce operations

  • Per-user Salesforce client caching - Efficient connection management

  • Dual transport modes - STDIO for local clients, HTTP for multi-user deployments

  • RFC-compliant OAuth - RFC 8414, RFC 9728, RFC 7591, PKCE support

  • Client OAuth flexibility - ADK agents, Claude Code, Gemini CLI all supported

Available Tools

Category

Tools

Query

salesforce_query, salesforce_query_all, salesforce_query_more, salesforce_search

Records

salesforce_get_record, salesforce_create_record, salesforce_update_record, salesforce_delete_record, salesforce_upsert_record

Metadata

salesforce_describe_object, salesforce_list_objects, salesforce_get_object_fields

Bulk API

salesforce_bulk_query, salesforce_bulk_insert, salesforce_bulk_update, salesforce_bulk_delete

Related MCP server: MCP Salesforce Lite

Prerequisites

Installation

uvx salesforce-mcp-server --transport stdio
# or for HTTP mode:
uvx salesforce-mcp-server --transport http

Option 2: Docker

docker pull ghcr.io/hypn4/salesforce-mcp-server

# HTTP mode (default)
docker run -p 8000:8000 \
  -e SALESFORCE_CLIENT_ID=your_client_id \
  -e SALESFORCE_LOGIN_URL=https://login.salesforce.com \
  ghcr.io/hypn4/salesforce-mcp-server

# STDIO mode
docker run -i \
  -e SALESFORCE_ACCESS_TOKEN=your_token \
  -e SALESFORCE_INSTANCE_URL=https://your-domain.my.salesforce.com \
  ghcr.io/hypn4/salesforce-mcp-server --transport stdio

Option 3: Pre-built Binary

Download from GitHub Releases:

Platform

Download

Linux (x64)

salesforce-mcp-server-linux-amd64.tar.gz

Linux (ARM64)

salesforce-mcp-server-linux-arm64.tar.gz

macOS (ARM64)

salesforce-mcp-server-darwin-arm64.tar.gz

Windows (x64)

salesforce-mcp-server-windows-amd64.zip

Verify checksum:

# Download checksums-sha256.txt from the release
sha256sum -c checksums-sha256.txt

Option 4: From Source

git clone https://github.com/hypn4/salesforce-mcp-server.git
cd salesforce-mcp-server
cp .env.example .env
# Edit .env with your Salesforce credentials
uv sync

Configuration

All configuration is done through environment variables. Copy .env.example to .env and adjust as needed.

OAuth Mode

Variable

Default

Description

OAUTH_MODE

bearer

bearer for client-handled OAuth, proxy for server OAuth proxy

Bearer Mode (Default)

Clients handle OAuth themselves. The server validates Bearer tokens via Salesforce userinfo endpoint.

Variable

Default

Description

SALESFORCE_INSTANCE_URL

https://login.salesforce.com

Token verification URL

Proxy Mode

Server acts as OAuth 2.1 + PKCE proxy to Salesforce. Provides RFC-compliant endpoints:

  • /.well-known/oauth-authorization-server (RFC 8414)

  • /.well-known/oauth-protected-resource (RFC 9728)

  • /register (RFC 7591 Dynamic Client Registration)

  • /authorize, /token, /auth/callback (OAuth 2.1 + PKCE)

Variable

Required

Description

SALESFORCE_CLIENT_ID

Yes

Salesforce Connected App client ID

SALESFORCE_CLIENT_SECRET

No

Client secret (optional, see modes below)

SALESFORCE_LOGIN_URL

No

Login URL (default: https://login.salesforce.com)

BASE_URL

No

Public URL of the server (default: http://localhost:8000)

OAUTH_REQUIRED_SCOPES

No

Comma-separated scopes (default: api,refresh_token)

Authentication Modes

Mode

SALESFORCE_CLIENT_SECRET

Use Case

Confidential Client

Set

Server-side apps where secret can be stored securely

PKCE-only (Public Client)

Empty/Unset

CLI tools, mobile apps, or when secret storage isn't possible

For PKCE-only mode, configure your Salesforce Connected App:

  • ✅ Enable "Require Proof Key for Code Exchange (PKCE)"

  • ❌ Disable "Require Secret for Web Server Flow"

Storage Configuration (Proxy Mode)

Variable

Default

Description

OAUTH_STORAGE_TYPE

memory

memory or redis

REDIS_URL

redis://localhost:6379

Redis connection URL

STORAGE_ENCRYPTION_KEY

-

Fernet key for token encryption

HTTP Server Settings

Variable

Default

Description

PORT

8000

HTTP server port (cloud platform standard)

FASTMCP_PORT

-

HTTP server port (fallback, for backwards compatibility)

Port Priority: PORT → FASTMCP_PORT → 8000 (default)

Cloud platforms (Heroku, Cloud Run, Railway, etc.) automatically set the PORT environment variable.

Salesforce Instance

Variable

Default

Description

SALESFORCE_LOGIN_URL

https://login.salesforce.com

For sandbox use https://test.salesforce.com

SALESFORCE_INSTANCE_URL

https://login.salesforce.com

Token verification URL (userinfo endpoint)

Logging

Variable

Default

Description

LOG_LEVEL

INFO

DEBUG, INFO, WARNING, ERROR

MCP Integration Guide

Authentication Modes

This server supports two OAuth modes:

Bearer Token Mode (Default)

Standard MCP authentication pattern (like GitHub, Stripe MCP servers):

  • Server: Validates Bearer tokens via Salesforce userinfo endpoint

  • Clients: Handle OAuth authentication themselves

Client Type

OAuth Handling

ADK Agents

Use auth_scheme + auth_credential in McpToolset

Claude Desktop/Code/Gemini CLI

Static access token via environment variables (STDIO Mode)

OAuth Proxy Mode

Full OAuth 2.1 + PKCE proxy with RFC-compliant discovery:

  • Server: Handles complete OAuth flow with Salesforce

  • Clients: Use standard OAuth discovery (automatic with compatible clients)

Client Type

OAuth Handling

Claude Desktop

Native OAuth discovery (automatic)

Claude Code

Native OAuth discovery (automatic)

Gemini CLI

Native OAuth discovery (automatic)

ADK Agents

StreamableHTTPConnectionParams with Bearer token

To enable proxy mode:

export OAUTH_MODE=proxy
export SALESFORCE_CLIENT_ID=your_client_id
export BASE_URL=https://your-server.com

# Optional: Add client_secret for confidential client mode
# Omit for PKCE-only (public client) mode
export SALESFORCE_CLIENT_SECRET=your_client_secret

Transport Modes

Mode

Authentication

Use Case

STDIO

Access Token (env vars)

Local development, single-user

HTTP

Bearer Token (Authorization header)

Multi-user, web-based clients

STDIO Mode Environment Variables

Variable

Required

Description

SALESFORCE_ACCESS_TOKEN

Yes

Salesforce Access Token

SALESFORCE_INSTANCE_URL

Yes

Salesforce Instance URL (e.g., https://your-domain.my.salesforce.com)

SALESFORCE_USER_ID

No

User ID (default: env_user)

SALESFORCE_ORG_ID

No

Org ID (default: env_org)

SALESFORCE_USERNAME

No

Username (default: env_user)

Getting an Access Token for STDIO Mode

Use Salesforce CLI to get your Access Token:

sf org display --target-org <your-org-alias>

From the output, copy the Access Token and Instance Url values for your configuration.


Claude Desktop

Config file location:

  • macOS/Linux: ~/.config/claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

OAuth Proxy Mode (Recommended)

Native OAuth 2.1 + PKCE - no additional tools required.

  1. Configure the server for proxy mode:

export OAUTH_MODE=proxy
export SALESFORCE_CLIENT_ID=your_connected_app_client_id
export BASE_URL=http://localhost:8000
# Optional: SALESFORCE_CLIENT_SECRET for confidential client mode
  1. Start the server:

uvx salesforce-mcp-server --transport http
  1. Configure Claude Desktop:

{
  "mcpServers": {
    "salesforce": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop will automatically discover OAuth endpoints and initiate authentication when you first use a Salesforce tool.

STDIO Mode (Static Token)

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["salesforce-mcp-server", "--transport", "stdio"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "00D...",
        "SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com"
      }
    }
  }
}

Claude Code

Config file location:

  • Global: ~/.claude/settings.json

  • Project: .mcp.json

OAuth Proxy Mode (Recommended)

Native OAuth 2.1 + PKCE - no additional tools required.

  1. Configure the server (see Configuration section above)

  2. Start the server:

uvx salesforce-mcp-server --transport http
  1. Add the MCP server:

claude mcp add salesforce --transport http http://localhost:8000/mcp

Or configure manually in ~/.claude/settings.json or .mcp.json:

{
  "mcpServers": {
    "salesforce": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code will automatically discover OAuth endpoints via RFC 8414 metadata.

STDIO Mode (Static Token)

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["salesforce-mcp-server", "--transport", "stdio"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "00D...",
        "SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com"
      }
    }
  }
}

Gemini CLI

Config file: ~/.gemini/settings.json

OAuth Proxy Mode (Recommended)

Native OAuth discovery - Gemini CLI auto-discovers OAuth endpoints.

  1. Configure the server (see Configuration section above)

  2. Start the server:

uvx salesforce-mcp-server --transport http
  1. Add the MCP server:

gemini mcp add salesforce http://localhost:8000/mcp

Or configure manually in ~/.gemini/settings.json:

{
  "mcpServers": {
    "salesforce": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Gemini CLI will automatically discover OAuth endpoints and initiate authentication.

STDIO Mode (Static Token)

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["salesforce-mcp-server", "--transport", "stdio"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "00D...",
        "SALESFORCE_INSTANCE_URL": "https://your-domain.my.salesforce.com"
      }
    }
  }
}

Running Manually

STDIO Mode:

uvx salesforce-mcp-server --transport stdio
# or with local development:
just run

HTTP Mode:

uvx salesforce-mcp-server --transport http
# or with local development:
just run-http

HTTP mode default endpoint: http://localhost:8000

Salesforce Connected App Setup

  1. In Salesforce Setup, navigate to App Manager

  2. Click New Connected App

  3. Fill in basic information (name, contact email)

  4. Enable OAuth Settings

  5. Set Callback URL to match your deployment:

    • For local development: http://localhost:8000/auth/callback

    • For production: https://your-domain.com/auth/callback

  6. Select OAuth scopes:

    • api (Access and manage your data)

    • refresh_token (Perform requests at any time)

    • offline_access (Perform requests at any time)

  7. Enable Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows

  8. Save and copy the Consumer Key (this is your SALESFORCE_CLIENT_ID)

Development

Commands

Command

Description

just run

Run server in STDIO mode

just run-http

Run server in HTTP mode

just run-debug

Run with DEBUG logging

just test

Run tests

just test-cov

Run tests with coverage

just lint

Run linter

just lint-fix

Run linter with auto-fix

just fmt

Format code

just inspector

Run with MCP Inspector for debugging

just tools

List all registered MCP tools

just docker-build

Build Docker image

just docker-run

Run in Docker (HTTP mode)

just docker-run-stdio

Run in Docker (STDIO mode)

just build-binary

Build standalone binary

Project Structure

salesforce-mcp-server/
├── src/salesforce_mcp_server/
│   ├── server.py          # FastMCP server setup
│   ├── tools/             # MCP tool implementations
│   │   ├── query.py       # SOQL/SOSL query tools
│   │   ├── records.py     # Record CRUD tools
│   │   ├── metadata.py    # Metadata tools
│   │   └── bulk.py        # Bulk API tools
│   ├── oauth/             # OAuth authentication
│   │   ├── proxy.py           # OAuth 2.1 proxy for Salesforce
│   │   ├── token_verifier.py  # Salesforce token validation
│   │   ├── token_access.py    # Token access utilities
│   │   ├── storage.py         # Token storage backends
│   │   └── pkce.py            # PKCE utilities
│   └── salesforce/        # Salesforce client
├── tests/
├── .env.example
├── justfile
└── pyproject.toml

License

MIT

Available Tools

16 tools
salesforce_bulk_deleteA

Bulk delete multiple records.

Use this to delete many records efficiently.

Args: sobject: SObject type (e.g., 'Account', 'Contact') record_ids: List of record IDs to delete. Example: ["001xx000...", "001xx000..."]

Returns: List of results for each record with success status

Inputs: sobject (required), record_ids (required). Returns: result

salesforce_bulk_insertA

Bulk insert multiple records.

Use this to create many records efficiently. The Bulk API processes records in batches and is optimized for high volumes.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead') records: List of records to insert. Each record is a dict of field name to value. Example: [{"Name": "Acme"}, {"Name": "Globex"}]

Returns: List of results for each record, containing: - success: Whether the insert succeeded - id: The new record ID (if successful) - errors: Any errors that occurred

Inputs: records (required), sobject (required). Returns: result

salesforce_bulk_queryA

Execute a bulk query for large data sets.

Use this for queries that may return more than 2,000 records. The Bulk API is optimized for large data volumes and runs asynchronously.

Args: sobject: SObject type being queried (e.g., 'Account', 'Contact') soql: SOQL query string

Returns: List of all matching records

Inputs: soql (required), sobject (required). Returns: result

salesforce_bulk_updateA

Bulk update multiple records.

Use this to update many records efficiently.

Args: sobject: SObject type (e.g., 'Account', 'Contact') records: List of records to update. Each record MUST include an 'Id' field to identify which record to update. Example: [ {"Id": "001xx...", "Industry": "Tech"}, {"Id": "001xx...", "Industry": "Finance"} ]

Returns: List of results for each record with success status

Inputs: records (required), sobject (required). Returns: result

salesforce_create_recordA

Create a new Salesforce record.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead') data: Record field values as key-value pairs. Example: {"Name": "Acme Corp", "Industry": "Technology"}

Returns: Created record info including: - id: The new record's ID - success: Whether creation succeeded - errors: Any errors that occurred

Inputs: data (required), sobject (required). Returns: object

salesforce_delete_recordA

Delete a Salesforce record.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead') record_id: Salesforce record ID (18-character ID)

Returns: Deletion result with success status

Inputs: sobject (required), record_id (required). Returns: object

salesforce_describe_objectA

Get metadata for a Salesforce SObject.

Returns detailed information about an object including its fields, relationships, record types, and other metadata.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead', 'Opportunity')

Returns: Object metadata including: - name: API name of the object - label: Display name - fields: List of field definitions with type, length, required, etc. - childRelationships: Related objects - recordTypeInfos: Available record types - keyPrefix: Object ID prefix - And more...

Inputs: sobject (required). Returns: object

salesforce_get_object_fieldsA

Get field information for a Salesforce SObject.

This is a convenience method that returns just the fields array from the describe call, which is often what's needed.

Args: sobject: SObject type (e.g., 'Account', 'Contact')

Returns: List of field definitions, each containing: - name: API name of the field - label: Display name - type: Field type (string, picklist, reference, etc.) - length: Maximum length for text fields - nillable: Whether the field can be null - createable: Whether the field can be set on create - updateable: Whether the field can be updated - picklistValues: For picklist fields, available values - referenceTo: For reference fields, related object(s)

Inputs: sobject (required). Returns: result

salesforce_get_recordA

Get a single Salesforce record by ID.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead') record_id: Salesforce record ID (18-character ID) fields: Optional list of specific fields to retrieve. If not provided, returns all accessible fields.

Returns: Record data with requested fields

Inputs: sobject (required), record_id (required), fields. Returns: object

salesforce_list_objectsA

List all available SObjects in the Salesforce org.

Returns a list of all objects accessible to the current user, including standard objects (Account, Contact, etc.) and custom objects.

Returns: List of object summaries, each containing: - name: API name - label: Display name - keyPrefix: Object ID prefix - custom: Whether it's a custom object - queryable: Whether SOQL queries are supported - createable: Whether records can be created - updateable: Whether records can be updated - deletable: Whether records can be deleted

Inputs: no named parameters. Returns: result

salesforce_queryA

Execute a SOQL query against Salesforce.

Args: soql: SOQL query string (e.g., "SELECT Id, Name FROM Account LIMIT 10") include_deleted: Include deleted and archived records (default: False)

Returns: Query results including: - totalSize: Total number of records matching the query - done: Whether all records have been returned - records: List of matching records - nextRecordsUrl: URL to fetch more records (if done is False)

Inputs: soql (required), include_deleted. Returns: object

salesforce_query_allA

Execute a SOQL query including deleted and archived records.

This is equivalent to calling salesforce_query with include_deleted=True.

Args: soql: SOQL query string

Returns: Query results including deleted/archived records

Inputs: soql (required). Returns: object

salesforce_query_moreA

Fetch additional records from a previous query.

Use this when a query returns done=False and provides a nextRecordsUrl.

Args: next_records_url: The nextRecordsUrl from a previous query response

Returns: Additional query results

Inputs: next_records_url (required). Returns: object

salesforce_update_recordB

Update an existing Salesforce record.

Args: sobject: SObject type (e.g., 'Account', 'Contact', 'Lead') record_id: Salesforce record ID (18-character ID) data: Fields to update as key-value pairs. Example: {"Industry": "Finance", "Website": "https://acme.com"}

Returns: Update result with success status

Inputs: data (required), sobject (required), record_id (required). Returns: object

salesforce_upsert_recordA

Upsert a record using an external ID field.

If a record with the external ID exists, it will be updated. Otherwise, a new record will be created.

Args: sobject: SObject type (e.g., 'Account', 'Contact') external_id_field: Name of the external ID field data: Record data including the external ID field value. Example: {"External_Id__c": "EXT-001", "Name": "Acme Corp"}

Returns: Upsert result with success status

Inputs: data (required), sobject (required), external_id_field (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have distinct, clearly described purposes: query vs. search vs. bulk vs. CRUD. However, salesforce_query_all redundantly duplicates salesforce_query with include_deleted=True, and salesforce_get_object_fields is a subset of salesforce_describe_object, creating minor overlap.

    Naming Consistency4/5

    The salesforce_ prefix and verb_noun structure are mostly consistent (create_record, update_record, delete_record, bulk_insert). A few names deviate from the strict verb_noun pattern, such as salesforce_query, salesforce_query_more, salesforce_query_all, and salesforce_search, but the overall convention is clear and predictable.

    Tool Count4/5

    With 16 tools, the set is slightly above the typical 3-15 range but is justified by the breadth of Salesforce operations covered. The redundant salesforce_query_all and the convenience-only salesforce_get_object_fields could be removed without losing capability.

    Completeness4/5

    The server covers the core Salesforce lifecycle well: SOQL/SOSL querying, single-record CRUD, upsert, metadata inspection, and bulk insert/update/delete. Notable minor gaps include no bulk upsert and no undelete/recycle-bin operation, but the main workflows are well supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Salesforce organizations through natural language by exposing Salesforce APIs (REST, Bulk v2, GraphQL, Tooling, Auth) as MCP tools for querying data, managing records, and executing SOQL queries.
      28 npm
      19
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to securely interact with Salesforce CRM data through SOQL queries, CRUD operations, and metadata exploration. Supports connecting to Salesforce objects like Accounts, Contacts, and Opportunities via OAuth 2.0 authentication.
      8
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Salesforce CRM by executing SOQL queries and performing CRUD operations on records such as Leads. It supports secure OAuth 2.0 authentication and provides management for both standard and custom Salesforce fields.
      -