README.md•6.05 kB
# 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+**
```bash
# macOS (via Homebrew)
brew install python@3.11
# Or download directly from Python.org
# https://www.python.org/downloads/
```
**2. Poetry**
```bash
# Install Poetry (official installer)
curl -sSL https://install.python-poetry.org | python3 -
# Verify installation
poetry --version
```
**3. Node.js**
```bash
# macOS (via Homebrew)
brew install node
# Or download from Node.js website
# https://nodejs.org/
```
**4. Salesforce CLI**
```bash
# 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:
```bash
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):
```bash
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:
1. **Install prerequisites** (see Prerequisites section above)
2. **Install Python dependencies:**
```bash
poetry install
```
3. **Authenticate with Salesforce:**
```bash
sf org login web
```
4. **Create `.env` file** with your Salesforce org details:
```bash
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
```
5. **Configure Claude Desktop** by adding this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"sfmcp": {
"command": "/path/to/your/sfmcp/run-mcp.sh",
"args": []
}
}
}
```
6. **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):**
```bash
poetry run sfmcp-stdio
# or
./scripts/run_stdio.sh
```
**HTTP Mode (for testing):**
```bash
poetry run sfmcp-http
# or
./scripts/run_http.sh
```
### Code Quality
```bash
# 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