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

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

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

Bearer Mode (Default)

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

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)

Authentication Modes

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)

HTTP Server Settings

Port Priority: PORT → FASTMCP_PORT → 8000 (default)

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

Salesforce Instance

Logging

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

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)

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

STDIO Mode Environment Variables

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

2. Start the server:

uvx salesforce-mcp-server --transport http

3. 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

3. 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

3. 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

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