npm package: @plugix/mcp-salesforce
Description: MCP Server for Salesforce CRM - Leads, Contacts, Opportunities, Cases
Author: Plugix
Latest version: 0.1.0

# Salesforce CRM MCP Server

MCP server for Salesforce CRM integration. Manage leads, contacts, opportunities, accounts, and cases through AI-powered workflows.

## Features

- **get_leads** - Query leads with filters (status, source, search)
- **get_contacts** - Query contacts with filters (account, search)
- **get_opportunities** - Query opportunities with filters (stage, amount, status)
- **get_accounts** - Query accounts with filters (type, industry, search)
- **get_cases** - Query support cases with filters (status, priority, account)
- **create_lead** - Create new leads (with confirmation)
- **update_opportunity** - Update opportunity details (with confirmation)
- **search_records** - Search across multiple Salesforce objects

## Installation

```bash
npm install @plugix/mcp-salesforce
```

Or clone and build locally:

```bash
git clone https://github.com/plugix/ai-integration.git
cd ai-integration/mcp-servers/salesforce
npm install
npm run build
```

## Configuration

Create a `.env` file or set environment variables:

```env
# Plugix AI Platform (required)
API_URL=wss://api.plugix.ai
API_TOKEN=plx_live_your_token_here

# Salesforce credentials (required)
SALESFORCE_USERNAME=your_salesforce_username
SALESFORCE_PASSWORD=your_salesforce_password
SALESFORCE_SECURITY_TOKEN=your_security_token

# Salesforce login URL (optional)
# Use https://test.salesforce.com for sandbox environments
SALESFORCE_LOGIN_URL=https://login.salesforce.com

# Optional instance identification
INSTANCE_ID=salesforce-prod
INSTANCE_NAME=Production Salesforce
```

### Getting Salesforce Credentials

1. **Username**: Your Salesforce login email
2. **Password**: Your Salesforce password
3. **Security Token**:
   - Go to Salesforce Setup > Personal Settings > Reset My Security Token
   - The token will be emailed to you
   - If your IP is whitelisted, the token may not be required

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### NPX (without installation)

```bash
API_TOKEN=plx_live_xxx \
SALESFORCE_USERNAME=user@example.com \
SALESFORCE_PASSWORD=password \
SALESFORCE_SECURITY_TOKEN=token \
npx @plugix/mcp-salesforce
```

### Docker

```bash
docker build -t mcp-salesforce .
docker run --env-file .env mcp-salesforce
```

## Tools Reference

### get_leads

Query leads from Salesforce CRM.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| status | string | Filter by lead status (e.g., Open, Contacted, Qualified) |
| source | string | Filter by lead source (e.g., Web, Phone, Partner) |
| search | string | Search in name, company, or email |
| limit | number | Max results (default: 20, max: 100) |

**Example:**
```json
{
  "name": "get_leads",
  "arguments": {
    "status": "Open - Not Contacted",
    "limit": 10
  }
}
```

### get_contacts

Query contacts from Salesforce CRM.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| account_id | string | Filter by Account ID |
| search | string | Search in name or email |
| limit | number | Max results (default: 20, max: 100) |

### get_opportunities

Query sales opportunities.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| account_id | string | Filter by Account ID |
| stage_name | string | Filter by stage (e.g., Prospecting, Closed Won) |
| is_closed | boolean | Filter by closed status |
| is_won | boolean | Filter by won status |
| min_amount | number | Minimum opportunity amount |
| max_amount | number | Maximum opportunity amount |
| limit | number | Max results (default: 20, max: 100) |

**Example:**
```json
{
  "name": "get_opportunities",
  "arguments": {
    "stage_name": "Negotiation",
    "min_amount": 10000
  }
}
```

### get_accounts

Query accounts (companies/organizations).

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| type | string | Filter by account type (e.g., Customer, Partner) |
| industry | string | Filter by industry |
| search | string | Search in account name |
| limit | number | Max results (default: 20, max: 100) |

### get_cases

Query support cases.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| account_id | string | Filter by Account ID |
| contact_id | string | Filter by Contact ID |
| status | string | Filter by status (e.g., New, Working, Closed) |
| priority | string | Filter by priority (High, Medium, Low) |
| is_closed | boolean | Filter by closed status |
| limit | number | Max results (default: 20, max: 100) |

### create_lead

Create a new lead. Requires confirmation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| last_name | string | Yes | Lead's last name |
| company | string | Yes | Company name |
| confirmed | boolean | Yes | Must be `true` to create |
| first_name | string | No | Lead's first name |
| email | string | No | Email address |
| phone | string | No | Phone number |
| title | string | No | Job title |
| status | string | No | Lead status (default: Open - Not Contacted) |
| lead_source | string | No | Lead source |
| industry | string | No | Industry |
| description | string | No | Additional notes |

**Example:**
```json
{
  "name": "create_lead",
  "arguments": {
    "first_name": "John",
    "last_name": "Doe",
    "company": "Acme Inc",
    "email": "john@acme.com",
    "lead_source": "Web",
    "confirmed": true
  }
}
```

### update_opportunity

Update an existing opportunity. Requires confirmation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | Salesforce Opportunity ID |
| confirmed | boolean | Yes | Must be `true` to update |
| name | string | No | Opportunity name |
| stage_name | string | No | Opportunity stage |
| amount | number | No | Deal amount |
| close_date | string | No | Expected close date (YYYY-MM-DD) |
| probability | number | No | Win probability (0-100) |
| next_step | string | No | Next action item |
| description | string | No | Additional notes |

**Example:**
```json
{
  "name": "update_opportunity",
  "arguments": {
    "id": "006XXXXXXXXXXXXXXX",
    "stage_name": "Closed Won",
    "amount": 50000,
    "confirmed": true
  }
}
```

### search_records

Search across multiple Salesforce objects using SOSL.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | Yes | Search term |
| objects | array | No | Objects to search (default: Lead, Contact, Account, Opportunity, Case) |
| limit | number | No | Max results per object (default: 20) |

**Example:**
```json
{
  "name": "search_records",
  "arguments": {
    "query": "Acme",
    "objects": ["Account", "Contact", "Opportunity"]
  }
}
```

## Security

This MCP server follows the Plugix security model:

- **Credentials stay local**: Salesforce username, password, and security token never leave your server
- **Data passes through**: Product/contact data passes through Plugix API for AI processing but is not stored
- **Confirmation required**: All write operations (create_lead, update_opportunity) require explicit confirmation

## Salesforce API Requirements

Your Salesforce org needs:

1. **API Access** enabled for your user profile
2. **Appropriate permissions** on Lead, Contact, Account, Opportunity, and Case objects
3. **Security Token** (unless your IP is whitelisted)

### Recommended Permissions

- Read/Write on Lead
- Read/Write on Contact
- Read/Write on Account
- Read/Write on Opportunity
- Read on Case

## Testing

```bash
npm test
```

## Troubleshooting

### "INVALID_LOGIN" error
- Verify username and password are correct
- Make sure security token is appended to password (or provided separately)
- Check if your IP needs to be whitelisted in Salesforce

### "INSUFFICIENT_ACCESS" error
- Verify your Salesforce user has API access enabled
- Check object-level permissions for the objects you're querying

### "REQUEST_LIMIT_EXCEEDED" error
- You've hit Salesforce API limits
- Consider implementing caching or reducing query frequency

### Connection refused to Plugix API
- Check `API_URL` is correct
- Verify `API_TOKEN` is valid
- Ensure firewall allows outbound WebSocket connections

## License

MIT