# salesforce-marketing-mcp

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)

A production-ready [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI assistants (Claude, Cursor, etc.) direct access to Salesforce CRM data. Built for **marketing ops**, **revenue ops**, and **B2B marketing teams** who want AI-assisted access to leads, contacts, campaigns, campaign members, tasks, and 14 reporting tools — all without writing SOQL.

---

## Features

- **Leads** — Search, get, create, update, and convert leads
- **Contacts** — Search, get, create, update, and look up by email
- **Accounts** — Search, get, and list contacts per account
- **Campaigns** — List, get, create, and update campaigns
- **Campaign Members** — List members, add individuals, bulk-add up to 200, update statuses
- **Tasks** — Create tasks; list by lead, contact, or campaign
- **Analytics Reports** — List, run, and describe Salesforce Analytics reports
- **Campaign Analytics** — ROI calc, member status breakdown, top campaigns, performance trends
- **Attribution** — Lead source breakdown, pipeline by campaign, CampaignInfluence, won revenue by campaign, lead conversion metrics
- **Pipeline** — Pipeline summary, pipeline by lead source, MQL trend, forecast summary
- **Activity** — Activity summary by dimension, recent activities by lead or contact
- **Power tools** — Raw SOQL, SObject describe, list all objects

---

## Prerequisites

- A Salesforce org (any edition with API access)
- Your Salesforce **username**, **password**, and **security token**
  - To get/reset your security token: *Settings > Personal Information > Reset My Security Token*
- Node.js 20 or later

No connected app or OAuth setup required.

---

## Setup

### 1. Install

```bash
npm install -g salesforce-marketing-mcp
# or run directly with npx
npx salesforce-marketing-mcp
```

### 2. Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `SF_USERNAME` | Yes | — | Salesforce login email |
| `SF_PASSWORD` | Yes | — | Salesforce password |
| `SF_SECURITY_TOKEN` | Yes | — | Security token (appended to password on login) |
| `SF_LOGIN_URL` | No | `https://login.salesforce.com` | Use `https://test.salesforce.com` for sandboxes |
| `SF_API_VERSION` | No | `60.0` | Salesforce API version |

Create a `.env` file or set them in your shell:

```bash
export SF_USERNAME="you@yourcompany.com"
export SF_PASSWORD="yourpassword"
export SF_SECURITY_TOKEN="yourtoken"
# For sandbox:
export SF_LOGIN_URL="https://test.salesforce.com"
```

---

## Usage

### Claude Desktop

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

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["salesforce-marketing-mcp"],
      "env": {
        "SF_USERNAME": "you@yourcompany.com",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourtoken",
        "SF_LOGIN_URL": "https://login.salesforce.com"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add salesforce-marketing-mcp \
  -e SF_USERNAME=you@yourcompany.com \
  -e SF_PASSWORD=yourpassword \
  -e SF_SECURITY_TOKEN=yourtoken \
  -- npx salesforce-marketing-mcp
```

### Cursor

In `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["salesforce-marketing-mcp"],
      "env": {
        "SF_USERNAME": "you@yourcompany.com",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourtoken"
      }
    }
  }
}
```

---

## Tools reference

| Tool | Description |
|---|---|
| `sf_search_leads` | SOSL search across lead name, email, and company |
| `sf_get_lead` | Full lead record by ID |
| `sf_create_lead` | Create a new lead |
| `sf_update_lead` | Update any lead fields |
| `sf_convert_lead` | Convert lead to Account / Contact / Opportunity |
| `sf_search_contacts` | SOSL search across contact name and email |
| `sf_get_contact` | Full contact record with Account name |
| `sf_create_contact` | Create a new contact |
| `sf_update_contact` | Update any contact fields |
| `sf_contact_by_email` | Find contacts by email address (up to 10 matches) |
| `sf_search_accounts` | SOSL search on account name |
| `sf_get_account` | Account record with open opp count and lead count |
| `sf_list_account_contacts` | Contacts associated with an account |
| `sf_list_campaigns` | List campaigns with optional status/type/active filters |
| `sf_get_campaign` | Full campaign record with all performance metrics |
| `sf_create_campaign` | Create a new campaign |
| `sf_update_campaign` | Update any campaign fields |
| `sf_get_campaign_members` | List campaign members with lead/contact details |
| `sf_add_campaign_member` | Add a single lead or contact to a campaign |
| `sf_bulk_add_campaign_members` | Add up to 200 leads/contacts in one call |
| `sf_update_campaign_member_status` | Update member status and HasResponded flag |
| `sf_create_task` | Create a task linked to a lead, contact, or campaign |
| `sf_list_tasks_by_lead` | Tasks associated with a lead |
| `sf_list_tasks_by_contact` | Tasks associated with a contact |
| `sf_list_tasks_by_campaign` | Tasks associated with a campaign |
| `sf_list_reports` | List available Salesforce Analytics reports |
| `sf_run_report` | Execute a report and return structured rows |
| `sf_get_report_metadata` | Column definitions and groupings for a report |
| `sf_campaign_roi` | ROI, CPL, CPO, and response rate per campaign |
| `sf_campaign_member_status_breakdown` | Member status counts for a campaign |
| `sf_top_campaigns` | Rank campaigns by responses, opps, or won revenue |
| `sf_campaign_performance_trend` | Member additions over time (week/month) |
| `sf_lead_source_breakdown` | Lead volume, conversions, and revenue by lead source |
| `sf_pipeline_by_campaign` | Open pipeline grouped by campaign and stage |
| `sf_campaign_influence` | CampaignInfluence records linking campaigns to opps |
| `sf_won_revenue_by_campaign` | Closed-won revenue grouped by primary campaign |
| `sf_lead_conversion_metrics` | Conversion rates by lead source or campaign |
| `sf_pipeline_summary` | Pipeline by stage: count, amount, probability, weighted |
| `sf_pipeline_by_lead_source` | Pipeline grouped by lead source |
| `sf_mql_trend` | MQL (or any status) volume over time |
| `sf_forecast_summary` | Expected revenue for opps closing in a date range |
| `sf_activity_summary` | Task/event counts by lead source, campaign, or owner |
| `sf_recent_activities_by_lead` | Tasks and events for a specific lead |
| `sf_recent_activities_by_contact` | Tasks and events for a specific contact |
| `sf_run_soql` | Execute raw SOQL (escape hatch for custom queries) |
| `sf_describe_object` | Full field metadata for any SObject |
| `sf_list_objects` | List all queryable SObjects with optional filter |

---

## Example prompts

Once connected, ask Claude questions like:

> "What are my top 5 campaigns by won revenue this quarter?"

> "Show me the lead source breakdown for the last 90 days — include conversion rates."

> "Create a follow-up task for lead 00Q... due next Friday."

> "Which campaigns have the highest ROI? Include cost per lead."

> "Show me the MQL trend by month for this year."

> "Add all leads from this list to the Q2 Webinar campaign with status 'Invited'."

> "What's our current pipeline summary by stage with weighted values?"

---

## How it works

- **Auth**: Connects via Salesforce username + password + security token using [jsforce](https://jsforce.github.io). The connection is cached for 25 minutes and automatically refreshed on `INVALID_SESSION_ID` errors.
- **Production and sandbox**: Set `SF_LOGIN_URL=https://test.salesforce.com` to target a sandbox.
- **Rate limits**: All queries respect Salesforce API limits. Use `limit` parameters to control result sizes.

---

## License

MIT