# Salesforce MCP Server

A **Model Context Protocol (MCP)** server for **Salesforce CRM integration**. This server provides tools to interact with Salesforce Leads through the MCP protocol, enabling AI assistants, workflows, and copilots to manage Salesforce CRM lead data safely.

---

## Features

### Lead Sync Integration 
- **Automated Lead Syncing**: Sync leads from your platform into Salesforce CRM using a safe upsert-like flow
- **Duplicate Prevention**: Checks existing leads by email before creating a new one
- **Idempotent Operations**: Safe to call multiple times with the same data - no duplicates
- **Lead Status Handling**:
  - `scheduled` → triggers Lead Conversion
  - `objected` → updates Lead status only (no conversion)
- **SOQL Safe Queries**: Email values are escaped to prevent query-breaking characters
- **Error Handling**: Clear validation and authentication errors returned in JSON format
- **Correlation IDs**: Every tool response contains a correlation ID for debugging

---

### Lead Management
- **Full CRUD Operations**: Complete lead management capabilities
  - List leads with limit support
  - Get lead by email
  - Create new lead
  - Update existing lead fields
  - Delete lead
  - Update lead status
  - Sync lead (upsert by email)

---

### Technical Features
- **OAuth Integration**: Accepts Salesforce bearer tokens via request headers
- **Type-Safe**: Built with Pydantic schemas for strong validation
- **Switch/Match Tool Routing**: Clean tool routing using `match case`
- **CORS Support**: Fully configurable CORS support via `config.py`
- **Streamable HTTP Transport**: Uses MCP `StreamableHTTPSessionManager`
- **Postman Compatible**: Designed to work correctly with Postman MCP testing

---

## Prerequisites

- Python 3.10 or higher
- UV package manager
- Salesforce OAuth access token + refresh token (from OAuth service)
- Salesforce instance URL

---

## Installation

1. Clone the repository:
  ```bash
    git clone <your-repo-url>
    cd salesforce-mcp
 ```
2. Install dependencies using UV:
 ```bash
    uv sync add
 ```

# Edit .env and add your Salesforce config
.env

 ```bash
    SF_CLIENT_ID=your_salesforce_client_id
    SF_CLIENT_SECRET=your_salesforce_client_secret
    
    SF_TOKEN_URL=https://login.salesforce.com/services/oauth2/token
    SF_INSTANCE_URL=https://yourInstance.my.salesforce.com
    SF_API_VERSION=v59.0
    
    MCP_HOST=0.0.0.0
    MCP_PORT=3333
 ```

# Authentication (Required Headers)
This MCP server expects authentication tokens via headers.

Required Headers Format
```bash
Authorization: Bearer <ACCESS_TOKEN>
X-SF-Refresh-Token: Bearer <REFRESH_TOKEN>
X-SF-Instance-Url: https://yourInstance.my.salesforce.com
Content-Type: application/json
Accept: application/json
```

⚠️ Important

```bash
Must include a space: Bearer <token>

Authorization:Bearer <token> ❌ will fail

Authorization: Bearer <token> ✅ correct
```
Usage
Running the Server
```bash
uv run python -m app.server
```

Server will start on:
```bash
(http://0.0.0.0:3333)
```



## Available Tools

### 1. `salesforce_sync_lead`

### 2. `salesforce_list_leads`

### 3. `salesforce_get_lead`

### 4. `salesforce_create_lead`

### 5. `salesforce_update_lead`

### 6. `salesforce_delete_lead`

### 7. `salesforce_update_lead_status`

# Response Format
All tool responses return:

```bash
{
  "success": true,
  "data": {},
  "correlation_id": "uuid",
  "status_code": 200
}
```

Validation Error Response
If validation fails, the server returns:

```bash
{
  "success": false,
  "error": "Validation Error",
  "details": [
    {
      "field": "email",
      "message": "field required"
    }
  ],
  "correlation_id": "uuid"
}
```
# Authentication Error Response
If required auth headers are missing, the server returns:

```bash
{
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required to access this resource",
    "details": {
      "authentication_requirements": [
        {
          "provider": "salesforce",
          "auth_type": "bearer",
          "header_name": "Authorization",
          "header_format": "Bearer {access_token}",
          "required_scopes": ["api", "refresh_token", "offline_access"],
          "token_source": "access_token"
        }
      ]
    }
  }
}
```


# Project Structure
```bash
salesforce-mcp/
├── app/
│   ├── server.py            # MCP server and tools
│   ├── salesforce_client.py # Salesforce REST/SOAP client
│   ├── schemas.py           # Pydantic request schemas
│   ├── constants.py         # Lead status + Salesforce fields/constants
│   ├── config.py            # Host/Port + CORS configuration
│   ├── utils.py             # Correlation ID + token extraction + SOQL escaping
├── tests/                   # (Optional) unit tests
├── pyproject.toml
├── .env.example
├── README.md
└── .gitignore
```

## 🐳 Docker Support
   This project is fully containerized, allowing you to run the Salesforce MCP server without installing local dependencies.

1. Build the Image
From the root directory, run:

```bash
docker build -t salesforce-mcp .
```

2. Run the Container
Ensure your .env file is populated with your Salesforce credentials, then run:

```bash
docker run -d -p 3333:3333 --name sf-server --env-file .env salesforce-mcp
```

3. Verify the Deployment
   


```bash
docker logs sf-server
```
Check if the server is active by viewing the logs    
INFO: Salesforce MCP Server active at 0.0.0.0:3333.


# License
MIT License

# Author
Sowmya ( sowmya@rapidinnovation.dev)