Salesforce MCP Server
Provides tools for querying, managing records, metadata, and bulk operations in Salesforce, enabling AI agents to interact with Salesforce CRM.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Salesforce MCP Server show me the last 5 opportunities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Salesforce MCP Server
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 |
|
Records |
|
Metadata |
|
Bulk API |
|
Related MCP server: MCP Salesforce Lite
Prerequisites
Python >= 3.14
uv package manager
Salesforce Connected App (see Connected App Setup)
Installation
Option 1: uvx (Recommended)
uvx salesforce-mcp-server --transport stdio
# or for HTTP mode:
uvx salesforce-mcp-server --transport httpOption 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 stdioOption 3: Pre-built Binary
Download from GitHub Releases:
Platform | Download |
Linux (x64) |
|
Linux (ARM64) |
|
macOS (ARM64) |
|
Windows (x64) |
|
Verify checksum:
# Download checksums-sha256.txt from the release
sha256sum -c checksums-sha256.txtOption 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 syncConfiguration
All configuration is done through environment variables. Copy .env.example to .env and adjust as needed.
OAuth Mode
Variable | Default | Description |
|
|
|
Bearer Mode (Default)
Clients handle OAuth themselves. The server validates Bearer tokens via Salesforce userinfo endpoint.
Variable | Default | Description |
|
| 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 |
| Yes | Salesforce Connected App client ID |
| No | Client secret (optional, see modes below) |
| No | Login URL (default: |
| No | Public URL of the server (default: |
| No | Comma-separated scopes (default: |
Authentication Modes
Mode |
| 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 |
|
|
|
|
| Redis connection URL |
| - | Fernet key for token encryption |
HTTP Server Settings
Variable | Default | Description |
|
| HTTP server port (cloud platform standard) |
| - | HTTP server port (fallback, for backwards compatibility) |
Port Priority:
PORT→FASTMCP_PORT→8000(default)Cloud platforms (Heroku, Cloud Run, Railway, etc.) automatically set the
PORTenvironment variable.
Salesforce Instance
Variable | Default | Description |
|
| For sandbox use |
|
| Token verification URL (userinfo endpoint) |
Logging
Variable | Default | Description |
|
|
|
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 |
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_secretTransport 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 |
| Yes | Salesforce Access Token |
| Yes | Salesforce Instance URL (e.g., |
| No | User ID (default: |
| No | Org ID (default: |
| No | Username (default: |
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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
OAuth Proxy Mode (Recommended)
Native OAuth 2.1 + PKCE - no additional tools required.
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 modeStart the server:
uvx salesforce-mcp-server --transport httpConfigure 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.jsonProject:
.mcp.json
OAuth Proxy Mode (Recommended)
Native OAuth 2.1 + PKCE - no additional tools required.
Configure the server (see Configuration section above)
Start the server:
uvx salesforce-mcp-server --transport httpAdd the MCP server:
claude mcp add salesforce --transport http http://localhost:8000/mcpOr 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.
Configure the server (see Configuration section above)
Start the server:
uvx salesforce-mcp-server --transport httpAdd the MCP server:
gemini mcp add salesforce http://localhost:8000/mcpOr 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 runHTTP Mode:
uvx salesforce-mcp-server --transport http
# or with local development:
just run-httpHTTP mode default endpoint: http://localhost:8000
Salesforce Connected App Setup
In Salesforce Setup, navigate to App Manager
Click New Connected App
Fill in basic information (name, contact email)
Enable OAuth Settings
Set Callback URL to match your deployment:
For local development:
http://localhost:8000/auth/callbackFor production:
https://your-domain.com/auth/callback
Select OAuth scopes:
api(Access and manage your data)refresh_token(Perform requests at any time)offline_access(Perform requests at any time)
Enable Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows
Save and copy the Consumer Key (this is your
SALESFORCE_CLIENT_ID)
Development
Commands
Command | Description |
| Run server in STDIO mode |
| Run server in HTTP mode |
| Run with DEBUG logging |
| Run tests |
| Run tests with coverage |
| Run linter |
| Run linter with auto-fix |
| Format code |
| Run with MCP Inspector for debugging |
| List all registered MCP tools |
| Build Docker image |
| Run in Docker (HTTP mode) |
| Run in Docker (STDIO mode) |
| 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.tomlLicense
MIT
Available Tools
16 toolssalesforce_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_searchA
Execute a SOSL full-text search.
Args: sosl: SOSL search string (e.g., "FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name)")
Returns: List of matching records grouped by object type
Inputs: sosl (required). Returns: result
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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Run SOQL queries to explore and retrieve Salesforce data. Access accounts, contacts, opportunities…
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm19MIT
- AlicenseAqualityDmaintenanceEnables 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.82MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityDmaintenanceConnects any MCP-compatible AI assistant directly to a Salesforce org for querying data, exploring schema, running Apex, and managing deployments.25 npmMIT