# Salesforce MCP Server

An MCP (Model Context Protocol) server that lets Claude query, create, update, and delete Salesforce records directly — using the [Simple Salesforce](https://github.com/simple-salesforce/simple-salesforce) Python package.

## Quickstart

### 1. Install dependencies

```bash
pip3 install mcp simple-salesforce
```

### 2. Get your Salesforce credentials

See `.env.example` for the required variables. The server reads these from environment variables passed via the Claude config below.

| Variable | Where to find it |
|----------|-----------------|
| `SF_USERNAME` | Your Salesforce login email |
| `SF_PASSWORD` | Your Salesforce password |
| `SF_SECURITY_TOKEN` | Salesforce > Settings > Reset My Security Token ([docs](https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm)) |
| `SF_DOMAIN` | Your My Domain prefix, e.g. `mycompany.my` (from your Salesforce URL `https://mycompany.my.salesforce.com`) |

### 3. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "python3",
      "args": ["/absolute/path/to/salesforce-mcp-server/server.py"],
      "env": {
        "SF_USERNAME": "your.name@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "your-token",
        "SF_DOMAIN": "your-org.my"
      }
    }
  }
}
```

Restart Claude Desktop. The Salesforce tools should appear in the tool picker.

### 3b. Add to Claude Code (alternative)

Add to `~/.claude.json` or a project-level `.mcp.json`:

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "python3",
      "args": ["/absolute/path/to/salesforce-mcp-server/server.py"],
      "env": {
        "SF_USERNAME": "your.name@company.com",
        "SF_PASSWORD": "your-password",
        "SF_SECURITY_TOKEN": "your-token",
        "SF_DOMAIN": "your-org.my"
      }
    }
  }
}
```

## Available Tools

### Metadata

| Tool | Parameters | Description |
|------|-----------|-------------|
| `sf_list_objects` | — | List all queryable objects in the org |
| `sf_describe_object` | `object_name` | Get all fields, types, and labels for an object |

### Query

| Tool | Parameters | Description |
|------|-----------|-------------|
| `sf_query` | `soql` | Run a SOQL query (up to 2000 records) |
| `sf_query_all` | `soql` | Run a SOQL query with auto-pagination (up to 10k records) |
| `sf_search` | `sosl` | Run a SOSL search across multiple objects |
| `sf_count` | `object_name`, `where_clause` (optional) | Quick record count |

### Create / Update / Delete

| Tool | Parameters | Description |
|------|-----------|-------------|
| `sf_create_record` | `object_name`, `data` (JSON string) | Create a new record |
| `sf_update_record` | `object_name`, `record_id`, `data` (JSON string) | Update a record |
| `sf_delete_record` | `object_name`, `record_id` | Delete a record |
| `sf_upsert_record` | `object_name`, `external_id_field`, `external_id`, `data` (JSON string) | Upsert by external ID |

## Example prompts

Once connected, you can ask Claude things like:

- "How many Accounts do we have?"
- "Show me all Contacts created this month"
- "What fields does the Opportunity object have?"
- "Create a new Contact with name Jane Doe and email jane@example.com"
- "Find all Accounts in the Technology industry with revenue over 1M"

## Troubleshooting

**`ModuleNotFoundError: No module named 'mcp'`**
Run `pip3 install mcp simple-salesforce` (you may need `--break-system-packages` on macOS with Homebrew Python).

**`Authentication failed`**
Double-check your security token — it resets whenever you change your password. Get a new one from Salesforce Settings > Reset My Security Token.

**`SF_DOMAIN format`**
Use just the My Domain prefix without `.salesforce.com`. For `https://mycompany.my.salesforce.com`, use `mycompany.my`.