salesforce-mcp-server

jasonjuela/salesforce-mcp-server

3.1

If you are the rightful owner of salesforce-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Salesforce MCP Server is a Node.js microservice that integrates with Salesforce and LLMs to provide natural language queries and structured responses.

Salesforce MCP Server

A Node.js (Express-based) server that implements a Salesforce-aware MCP (Model Context Protocol) microservice, designed to interface with any LLM (starting with OpenAI's API). This server can receive natural language input, retrieve Salesforce schema metadata via OAuth2 from a live org, and return structured LLM responses in text, markdown, charts, or tabular JSON format.

🚀 Features

  • Natural Language Interface: Ask questions about your Salesforce org in plain English
  • OAuth2 Authentication: Secure Salesforce authentication using OAuth2 Authorization Code flow
  • Schema Awareness: Understands custom objects, fields, and relationships
  • Multiple Response Formats: Returns data as text, markdown, tables, or charts
  • Streaming Support: Real-time streaming responses from OpenAI
  • Privacy-Aware Logging: Automatic PII redaction in logs
  • Namespace Support: Special handling for custom namespaces (like owsc__)

🏗️ Architecture

src/
├── app.js                 # Main Express application
├── routes/
│   ├── auth.js           # OAuth2 authentication routes
│   └── generate.js       # Main API endpoints
├── services/
│   ├── salesforceService.js  # Salesforce API integration
│   └── mcpService.js     # MCP prompt construction logic
├── llmAdapters/
│   └── openaiAdapter.js  # OpenAI API integration
├── middleware/
│   ├── auth.js           # JWT authentication middleware
│   └── errorHandlers.js  # Error handling middleware
└── utils/
    ├── logger.js         # Privacy-aware logging
    └── validation.js     # Input validation utilities

📦 Installation

  1. Clone the repository

    git clone <repository-url>
cd salesforce-mcp-server

  2. Install dependencies

    npm install

  3. Configure environment variables

    cp env.example .env

    Edit .env with your configuration:

    # Server Configuration
PORT=3000
NODE_ENV=development

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENAI_MODEL=gpt-4o

# Salesforce OAuth2 Configuration
SALESFORCE_CLIENT_ID=your-salesforce-client-id
SALESFORCE_CLIENT_SECRET=your-salesforce-client-secret
SALESFORCE_REDIRECT_URI=http://localhost:3000/auth/callback

# JWT Configuration
JWT_SECRET=your-jwt-secret-key-here

# Custom Namespace
CUSTOM_NAMESPACE=owsc__

  4. Start the server

    # Development mode with auto-reload
npm run dev

# Production mode
npm start

🔧 Configuration

Salesforce Connected App Setup

  1. In Salesforce Setup, create a new Connected App:

  2. Enable OAuth Settings:

    • Callback URL: http://localhost:3000/auth/callback
    • Selected OAuth Scopes:
      • Access and manage your data (api)
      • Perform requests on your behalf at any time (refresh_token, offline_access)
      • Access your basic information (id, profile, email, address, phone)

  3. Note the Consumer Key and Consumer Secret for your .env file

OpenAI Setup

  1. Get your API key from OpenAI Platform
  2. Add it to your .env file as OPENAI_API_KEY

🔐 Authentication Flow

  1. Initiate Login

    curl -X GET http://localhost:3000/auth/login

  2. Follow the returned URL to authenticate with Salesforce

  3. Use the returned JWT token in subsequent API calls:

    Authorization: Bearer <jwt-token>

📡 API Endpoints

Authentication

  • GET /auth/login - Initiate Salesforce OAuth2 login
  • GET /auth/callback - OAuth2 callback handler
  • POST /auth/refresh - Refresh access token
  • GET /auth/status - Check authentication status
  • POST /auth/logout - Logout

Main API

  • POST /api/generate - Main endpoint for natural language queries
  • GET /api/objects - Get all custom objects
  • GET /api/objects/:objectName - Get object metadata
  • GET /api/search?q=<term> - Search metadata

Generate Request Format

{
  "user_question": "What is owsc__Order__c?",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 4000
}

Response Format

{
  "type": "markdown",
  "content": "# owsc__Order__c Object\n\nThe **owsc__Order__c** object represents...",
  "metadata": {
    "objects": ["owsc__Order__c"],
    "intent": "explain_object",
    "confidence": 0.9,
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processingTime": 1234
  }
}

🧪 Test Scenarios

The server handles these types of questions:

Object & Field Understanding

"What is owsc__Action__c?"
"Explain the fields on owsc__Action_Item__c."
"What fields are on owsc__Shipment__c?"

Relationships & Schema Exploration

"How is owsc__Order__c related to Account?"
"List all custom objects in the owsc__ namespace."
"Show me the relationships for owsc__Product__c."

Data Queries

"What are my sales for July 2025?"
"Show me recent orders."
"List all accounts in the wine industry."

Visual Output

"Show a chart of sales by wine type."
"List barrels by age in a table."
"Create a visualization of order trends."

🔍 Response Types

The server returns responses in different formats based on the question:

  • text: Simple text responses
  • markdown: Formatted documentation with headers, lists, etc.
  • table: Structured tabular data
  • chart: Chart.js configuration for data visualization
  • json: Raw JSON data for complex structures

🛡️ Security Features

  • JWT Authentication: Secure token-based authentication
  • PII Redaction: Automatic removal of sensitive data from logs
  • Rate Limiting: Protection against API abuse
  • Input Validation: Comprehensive input sanitization
  • CORS Protection: Configurable cross-origin resource sharing

📝 Logging

The server includes privacy-aware logging that automatically redacts:

  • Email addresses
  • Salesforce record IDs
  • Credit card numbers
  • SSNs
  • Other PII patterns

Logs are stored in ./logs/ directory with rotation.

🚀 Development

Running Tests

npm test

Development Mode

npm run dev

Debugging

Set LOG_LEVEL=debug in your .env file for detailed logging.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and questions:

  1. Check the logs in ./logs/ directory
  2. Verify your .env configuration
  3. Ensure Salesforce Connected App is properly configured
  4. Check that your OpenAI API key is valid

🔗 Related Documentation