MCP Salesforce TypeScript Connector
A TypeScript implementation of a Model Context Protocol (MCP) server for Salesforce integration, allowing LLMs to interact with Salesforce data through SOQL queries, SOSL searches, and CRUD operations.
Features
- 🔐 Simplified Password Authentication: Secure OAuth 2.0 Resource Owner Password Credentials Flow
- 📊 SOQL & SOSL: Execute queries and searches against Salesforce
- 🔍 Metadata Access: Retrieve object fields, labels, and types
- ✏️ CRUD Operations: Create, read, update, and delete records
- 🛠️ Tooling API: Execute Tooling API requests
- ⚡ Apex REST: Execute Apex REST requests
- 🌐 REST API: Make direct REST API calls to Salesforce
- 🐳 Docker Ready: No hardcoded values, fully configurable via environment variables
- 🔄 Token Refresh: Automatic token refresh for long-running sessions
Available Tools
authenticate_password- Authenticate using username/password with OAuthrun_soql_query- Execute SOQL queriesrun_sosl_search- Execute SOSL searchesget_object_fields- Get metadata for Salesforce objectsget_record- Retrieve specific records by IDcreate_record- Create new recordsupdate_record- Update existing recordsdelete_record- Delete recordstooling_execute- Execute Tooling API requestsapex_execute- Execute Apex REST requestsrestful- Make direct REST API calls
Quick Start with Docker
Prerequisites
-
Create a Connected App in Salesforce:
- Go to Setup → Apps → App Manager → New Connected App
- Fill in basic information (App Name, API Name, Contact Email)
- Enable OAuth Settings
- Set callback URL:
http://localhost:8080/callback(required but not used) - Select OAuth Scopes:
- Access your basic information (id, profile, email, address, phone)
- Perform requests on your behalf at any time (refresh_token, offline_access)
- Access and manage your data (api)
- Save and note down the Consumer Key and Consumer Secret
-
Get your Security Token:
- Go to Setup → My Personal Information → Reset Security Token
- Check your email for the new security token
Using the Docker Image
Pull and run the latest Docker image:
# Pull the image
docker pull steffensbola/salesforce-mcp-ts:latest
# Run with your credentials
docker run -p 3000:3000 \
-e SALESFORCE_CLIENT_ID=your_consumer_key \
-e SALESFORCE_CLIENT_SECRET=your_consumer_secret \
-e SALESFORCE_USERNAME=your_username@domain.com \
-e SALESFORCE_PASSWORD=your_password \
-e SALESFORCE_SECURITY_TOKEN=your_security_token \
-e SALESFORCE_SANDBOX=true \
steffensbola/salesforce-mcp-ts:latest
MCP Configuration
VS Code using Docker image
Add to your .vscode/mcp.json:
{
"servers": {
"salesforce": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "SALESFORCE_CLIENT_ID=your_consumer_key",
"-e", "SALESFORCE_CLIENT_SECRET=your_consumer_secret",
"-e", "SALESFORCE_USERNAME=your_username@domain.com",
"-e", "SALESFORCE_PASSWORD=your_password",
"-e", "SALESFORCE_SECURITY_TOKEN=your_token",
"-e", "SALESFORCE_SANDBOX=true",
"steffensbola/salesforce-mcp-ts:latest"
]
}
}
}
You can also use volumes to mount a config file instead of passing environment variables:
{
"servers": {
"salesforce": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "${workspaceFolder}/.env:/app/.env",
"steffensbola/salesforce-mcp-ts:latest"
]
}
}
}
Claude Desktop using Docker image
Add to your claude_desktop_config.json:
{
"mcpServers": {
"salesforce": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "SALESFORCE_CLIENT_ID=your_consumer_key",
"-e", "SALESFORCE_CLIENT_SECRET=your_consumer_secret",
"-e", "SALESFORCE_USERNAME=your_username@domain.com",
"-e", "SALESFORCE_PASSWORD=your_password",
"-e", "SALESFORCE_SECURITY_TOKEN=your_token",
"-e", "SALESFORCE_SANDBOX=true",
"steffensbola/salesforce-mcp-ts:latest"
]
}
}
}
Environment Variables
The server requires the following environment variables:
Required (OAuth Authentication)
SALESFORCE_CLIENT_ID- Consumer Key from your Connected AppSALESFORCE_CLIENT_SECRET- Consumer Secret from your Connected AppSALESFORCE_USERNAME- Your Salesforce usernameSALESFORCE_PASSWORD- Your Salesforce passwordSALESFORCE_SECURITY_TOKEN- Your Salesforce security token
Optional
SALESFORCE_SANDBOX- Set to"true"for sandbox,"false"for production (default:"false")
Alternative (Direct Token Authentication)
Instead of username/password, you can use:
SALESFORCE_ACCESS_TOKEN- Direct access tokenSALESFORCE_INSTANCE_URL- Salesforce instance URL (e.g.,https://your-instance.my.salesforce.com)
Backward Compatibility
The server also supports alternative variable names:
SF_CONSUMER_KEY/SF_CONSUMER_SECRETSF_USERNAME/SF_PASSWORD/SF_SECURITY_TOKEN
Using Docker Compose
- Create a
.envfile with your environment variables:
SALESFORCE_CLIENT_ID=your_consumer_key
SALESFORCE_CLIENT_SECRET=your_consumer_secret
SALESFORCE_USERNAME=your_username@domain.com
SALESFORCE_PASSWORD=your_password
SALESFORCE_SECURITY_TOKEN=your_token
SALESFORCE_SANDBOX=true
DOCKER_HUB_USERNAME=steffensbola
- Run using Docker Compose:
docker-compose up -d
Examples
Using the Tools
Once connected, you can use the tools through your MCP client:
Authentication:
Please authenticate with Salesforce using my credentials
Query Data:
Run this SOQL query: SELECT Id, Name, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10
Search:
Search for contacts named "John" using SOSL
Get Metadata:
Get all the fields for the Contact object
Create Record:
Create a new Account with Name "Test Company" and Industry "Technology"
Troubleshooting
Common Issues
-
Authentication Failed
- Verify credentials are correct
- Check Connected App OAuth scopes include "Access and manage your data (api)"
- Ensure security token is current (reset if needed)
- Verify sandbox setting matches your org type
-
Container Won't Start
- Ensure both CLIENT_ID and CLIENT_SECRET are provided
- Check that all required environment variables are set
- Verify Docker has access to pull the image
-
Network Errors
- Check internet connection
- Verify Salesforce service status
- Check firewall settings allow outbound HTTPS connections
Debug Mode
For verbose logging, add the debug environment variable:
docker run -e DEBUG=true \
-e SALESFORCE_CLIENT_ID=... \
# ... other variables
steffensbola/salesforce-mcp-ts:latest
Contributing
See CONTRIBUTING.md for information about:
- Project architecture and development setup
- Running from source code
- Contributing guidelines and pull request process
License
MIT License - see LICENSE file for details.