Salesforce MCP Server

This server provides MCP (Model Context Protocol) tools for interacting with Salesforce using the sf CLI. It exposes Salesforce data and metadata through standardized MCP tools that can be used with Claude Desktop and other MCP clients.

Features

Query Tool (salesforce_query) - Run SOQL queries and return structured results
List Objects (salesforce_list_objects) - Get all Salesforce object names in your org
Describe Objects (salesforce_describe) - Get detailed field information for any Salesforce object
List Flows (salesforce_list_flows) - Get all Salesforce flows with status and version information
Describe Flow (salesforce_describe_flow) - Get the complete XML metadata for a specific flow
List Reports (salesforce_list_reports) - Get all Salesforce reports with folder and usage information
List Dashboards (salesforce_list_dashboards) - Get all Salesforce dashboards with folder and usage information

Prerequisites

Before running the configuration script, you must install these prerequisites:

macOS (this setup is optimized for macOS, but should work on Linux/Windows)
Python 3.11+ - Required for running the MCP server
Poetry - Python dependency management
Node.js - Required for Salesforce CLI
Salesforce CLI - Command line interface for Salesforce

Prerequisites Installation Guide

1. Python 3.11+

# macOS (via Homebrew)
brew install python@3.11

# Or download directly from Python.org
# https://www.python.org/downloads/

2. Poetry

# Install Poetry (official installer)
curl -sSL https://install.python-poetry.org | python3 -

# Verify installation
poetry --version

3. Node.js

# macOS (via Homebrew)
brew install node

# Or download from Node.js website
# https://nodejs.org/

4. Salesforce CLI

# Install via npm (requires Node.js)
npm install -g @salesforce/cli

# Verify installation
sf --version

Quick Prerequisites Check

Run these commands to verify all prerequisites are installed:

python3 --version    # Should be 3.11+
poetry --version     # Should show Poetry version
node --version       # Should show Node version
sf --version         # Should show Salesforce CLI version

Installation

Quick Start (after installing prerequisites):

git clone https://github.com/mattmahowald/sfmcp.git
cd sfmcp
./install.py  # Configures SFMCP for your Salesforce org

The configuration script will:

✅ Check all prerequisites are installed
📦 Install Python dependencies via Poetry
🔐 Authenticate with your Salesforce org (or select existing auth)
⚙️ Create .env configuration file
🖥️ Update Claude Desktop configuration

Prerequisites must be installed first - see the Prerequisites section above.

Manual Setup (Alternative)

If you prefer to set up manually:

Install prerequisites (see Prerequisites section above)
Install Python dependencies:
```
poetry install
```
Authenticate with Salesforce:
```
sf org login web
```

Create .env file with your Salesforce org details:

SF_INSTANCE_URL=https://your-org.my.salesforce.com
SF_ACCESS_TOKEN=your-access-token
SF_ORG_ALIAS=your-org-alias
SF_USERNAME=your-username

Configure Claude Desktop by adding this to your claude_desktop_config.json:

{
  "mcpServers": {
    "sfmcp": {
      "command": "/path/to/your/sfmcp/run-mcp.sh",
      "args": []
    }
  }
}

Restart Claude Desktop to load the new MCP server.

Usage

Once configured, you can use these tools in Claude Desktop conversations:

"List all Salesforce objects" - Uses salesforce_list_objects
"Describe the Account object" - Uses salesforce_describe
"Query all active accounts" - Uses salesforce_query
"List all flows" - Uses salesforce_list_flows
"Describe the Contact_Last_Reply_Date flow" - Uses salesforce_describe_flow
"List all reports" - Uses salesforce_list_reports
"List all dashboards" - Uses salesforce_list_dashboards

Example queries:

SELECT Id, Name FROM Account LIMIT 10
SELECT Id, Email FROM Contact WHERE Email != null

Development

Running the Server

STDIO Mode (for MCP clients):

poetry run sfmcp-stdio
# or
./scripts/run_stdio.sh

HTTP Mode (for testing):

poetry run sfmcp-http
# or
./scripts/run_http.sh

Code Quality

# Type checking
poetry run mypy sfmcp/

# Linting
poetry run ruff check sfmcp/

# Formatting
poetry run ruff format sfmcp/

Configuration

The server uses environment variables from .env file:

SF_INSTANCE_URL - Your Salesforce instance URL
SF_ACCESS_TOKEN - Salesforce access token (automatically managed)
SF_ORG_ALIAS - Alias for your Salesforce org
SF_USERNAME - Your Salesforce username
SFMCP_HTTP_HOST - HTTP server host (default: 127.0.0.1)
SFMCP_HTTP_PORT - HTTP server port (default: 3333)

Troubleshooting

"Prerequisites check failed"

Install missing prerequisites using the commands in the Prerequisites section
Verify installations with: python3 --version, poetry --version, node --version, sf --version

"Salesforce CLI not found"

Install Salesforce CLI: npm install -g @salesforce/cli
Verify Node.js is installed: node --version

"Authentication failed"

Run sf org list to check authenticated orgs
Re-authenticate: sf org login web
Re-run the configuration script: python install.py

"Permission denied"

Make sure you have proper Salesforce org permissions
Check that your access token hasn't expired
Try re-authenticating with sf org login web

"Poetry not found"

Install Poetry: curl -sSL https://install.python-poetry.org | python3 -
Add to PATH if needed: export PATH="$HOME/.local/bin:$PATH"
Restart your terminal and try again