Salesforce MCP Server

![Release](https://github.com/hypn4/salesforce-mcp-server/releases) ![Container](https://ghcr.io/hypn4/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 | 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 |

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 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: ```bash

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: ```bash 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.

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

Start the server:

uvx salesforce-mcp-server --transport http

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.

Configure the server (see Configuration section above)

Start the server:

uvx salesforce-mcp-server --transport http

Add the MCP server:

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

Or configure manually in ~/.claude/settings.json or .mcp.json: ``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 http

Add the MCP server:

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

Or configure manually in ~/.gemini/settings.json: ``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: ```bash uvx salesforce-mcp-server --transport stdio

or with local development:

just run ```

HTTP Mode: ```bash uvx salesforce-mcp-server --transport http

or with local development:

just run-http ```

HTTP 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/callback
For 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 | |---------|-------------| | 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

Salesforce MCP Server