MCP Server for Salesforce Integration Demo

Overview

This repository contains a lightweight MCP (Model Context Protocol) server demo designed to help developers connect and interact with a Salesforce instance while experimenting with model-driven workflows. The demo shows common integration patterns—authenticating to Salesforce, forwarding context to an LLM-compatible interface, and exercising basic API calls—so you can validate end-to-end flows quickly and safely.

The project is intended as an instructional scaffold rather than a production-ready platform. It demonstrates how to wire up OAuth credentials, map Salesforce operations into tool endpoints, and expose a small MCP-compatible API surface for tooling or local testing. Use it to prototype integrations, reproduce bugs, and validate how contextual model requests can drive Salesforce actions.

Features

• Minimal MCP-compatible server for testing model-driven integrations
• Example Salesforce authentication flow (OAuth / username-password or connected app)
• Simple endpoints to run sample queries and mutations against Salesforce
• Local development and Docker-friendly setup for quick trials
• Sample request/response patterns for use with LLMs or automated tools
• Health and diagnostics endpoints for smoke testing

Installation / Configuration

Prerequisites:

• Node.js 18+ (or compatible runtime)
• npm or yarn
• A Salesforce developer org or sandbox and credentials / connected app

Clone and install:

git clone https://github.com/lciesielski/mcp-salesforce-example.git
cd mcp-salesforce-example
npm install

Environment variables

Create a .env file (example below) in the project root and populate with your Salesforce credentials and server options:

# .env
PORT=3000
SALESFORCE_CLIENT_ID=your_connected_app_client_id
SALESFORCE_CLIENT_SECRET=your_connected_app_client_secret
SALESFORCE_USERNAME=your_salesforce_username
SALESFORCE_PASSWORD=your_password_and_security_token
SALESFORCE_LOGIN_URL=https://login.salesforce.com
MCP_API_KEY=secret-key-for-local-use

Common environment variables (table):

Run the server:

# development
npm run dev

# production build + start
npm run build
npm start

Docker (optional):

docker build -t mcp-salesforce-demo .
docker run -p 3000:3000 --env-file .env mcp-salesforce-demo

Available Resources

The demo exposes a small set of HTTP endpoints useful for testing. Adjust paths if the implementation differs in the repository.

• GET /health
  • Quick liveness check
  • Example:

    curl http://localhost:3000/health
    

• POST /mcp/v0/run (MCP-style entrypoint)
  • Accepts a JSON payload describing the model/context and desired action. Useful for testing how an LLM would call tools via MCP.
  • Example:

    curl -X POST http://localhost:3000/mcp/v0/run \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${MCP_API_KEY}" \
      -d '{"input":"Find accounts with overdue opportunities"}'
    

• POST /salesforce/query
  • Run a simple SOQL query against the configured org
  • Example:

    curl -X POST http://localhost:3000/salesforce/query \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${MCP_API_KEY}" \
      -d '{"soql":"SELECT Id, Name FROM Account LIMIT 5"}'
    

• POST /salesforce/execute
  • Execute simple create/update operations (demo-only; validate payloads manually)
  • Always test mutations in a sandbox or developer org first.

If a Postman collection or sample requests are included in the repo, import them to accelerate testing.

Use Cases

• Quick smoke tests of Salesforce connectivity
  • Use GET /health and /salesforce/query to confirm OAuth is configured and basic SOQL works before wiring into a larger system.
• Prototype LLM-assisted CRM actions
  • Send model prompts to /mcp/v0/run that include customer context; the server demonstrates how an LLM-driven tool could call Salesforce endpoints to fetch account data or create a lead.
• Validate OAuth and connected app configuration
  • Use the demo to iterate on connected app settings (scopes, callback URLs) and confirm token exchange works.
• CI-style integration tests
  • Run the server inside CI with a test Salesforce org, invoking a set of queries and simple mutations to ensure API compatibility during upgrades.

Notes and Best Practices

• This demo is intended for local development and learning. Do not store production credentials in plain .env files for long-term use.
• Prefer OAuth flows appropriate for your security posture (JWT or OAuth web server flow) when moving beyond a demo.
• Run mutations only against non-production environments unless you have explicit approval.
• Review rate limits and API usage limits for your Salesforce org while experimenting.

Repository and reference: https://github.com/lciesielski/mcp-salesforce-example