Salesforce MCP Server

# 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 OAuth - `run_soql_query` - Execute SOQL queries - `run_sosl_search` - Execute SOSL searches - `get_object_fields` - Get metadata for Salesforce objects - `get_record` - Retrieve specific records by ID - `create_record` - Create new records - `update_record` - Update existing records - `delete_record` - Delete records - `tooling_execute` - Execute Tooling API requests - `apex_execute` - Execute Apex REST requests - `restful` - Make direct REST API calls ## Quick Start with Docker ### Prerequisites 1. **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 2. **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: ```bash # 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`: ```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: ```json { "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`: ```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 App - `SALESFORCE_CLIENT_SECRET` - Consumer Secret from your Connected App - `SALESFORCE_USERNAME` - Your Salesforce username - `SALESFORCE_PASSWORD` - Your Salesforce password - `SALESFORCE_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 token - `SALESFORCE_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_SECRET` - `SF_USERNAME` / `SF_PASSWORD` / `SF_SECURITY_TOKEN` ## Using Docker Compose 1. Create a `.env` file with your environment variables: ```bash 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 ``` 2. Run using Docker Compose: ```bash 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 1. **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 2. **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 3. **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: ```bash docker run -e DEBUG=true \ -e SALESFORCE_CLIENT_ID=... \ # ... other variables steffensbola/salesforce-mcp-ts:latest ``` ## Contributing See [CONTRIBUTING.md](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](LICENSE) file for details. ## Links - [Salesforce Documentation](https://developer.salesforce.com/docs) - [Model Context Protocol](https://github.com/modelcontextprotocol/typescript-sdk) - [Docker Hub Repository](https://hub.docker.com/r/steffensbola/salesforce-mcp-ts)