# Directory Structure ``` ├── .env.example ├── .gitignore ├── dist │ ├── index.d.ts │ ├── index.js │ ├── services │ │ ├── salesforce.d.ts │ │ └── salesforce.js │ ├── types.d.ts │ └── types.js ├── Dockerfile ├── package-lock.json ├── package.json ├── README.md ├── smithery.yaml ├── src │ ├── evals │ │ └── evals.ts │ ├── index.ts │ ├── tools.ts │ └── types.ts └── tsconfig.json ``` # Files -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- ``` node_modules/ build/ .env *.log .DS_Store .env.backup ``` -------------------------------------------------------------------------------- /.env.example: -------------------------------------------------------------------------------- ``` SF_LOGIN_URL=https://login.salesforce.com [email protected] SF_PASSWORD=your-password SF_SECURITY_TOKEN=your-security-token ``` -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- ```markdown [](https://mseep.ai/app/kablewy-salesforce-mcp-server) # Salesforce MCP Server [](https://smithery.ai/server/salesforce-mcp-server) A Model Context Protocol server implementation for interacting with Salesforce through its REST API using jsforce. ### Installing via Smithery To install Salesforce Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/salesforce-mcp-server): ```bash npx -y @smithery/cli install salesforce-mcp-server --client claude ``` ## Features - Execute SOQL queries - Retrieve object metadata - Create, update, and delete records - Secure authentication handling - Real-time data access ## Setup 1. Clone the repository 2. Copy `.env.example` to `.env` and fill in your Salesforce credentials 3. Install dependencies: `npm install` 4. Build: `npm run build` 5. Start: `npm start` ## Usage The server exposes several functions: ### query Execute SOQL queries against your Salesforce instance: ```json { "name": "query", "parameters": { "query": "SELECT Id, Name FROM Account LIMIT 5" } } ``` ### describe-object Get metadata about a Salesforce object: ```json { "name": "describe-object", "parameters": { "objectName": "Account" } } ``` ### create Create a new record: ```json { "name": "create", "parameters": { "objectName": "Contact", "data": { "FirstName": "John", "LastName": "Doe", "Email": "[email protected]" } } } ``` ### update Update an existing record: ```json { "name": "update", "parameters": { "objectName": "Contact", "data": { "Id": "003XXXXXXXXXXXXXXX", "Email": "[email protected]" } } } ``` ### delete Delete a record: ```json { "name": "delete", "parameters": { "objectName": "Contact", "id": "003XXXXXXXXXXXXXXX" } } ``` ## Running evals The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found [here](https://www.mcpevals.io/docs). ```bash OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools.ts ``` ## Security Make sure to: - Keep your `.env` file secure and never commit it - Use IP restrictions in Salesforce when possible - Regularly rotate your security token - Consider implementing additional authentication for the MCP server ## Contributing Contributions are welcome! Please submit PRs with improvements. # Salesforce MCP Server A Model Context Protocol server implementation for interacting with Salesforce through its REST API using jsforce. ### Installing via Smithery To install Salesforce Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/salesforce-mcp-server): ```bash npx -y @smithery/cli install salesforce-mcp-server --client claude ``` ## Features - Execute SOQL queries - Retrieve object metadata - Create, update, and delete records - Secure authentication handling - Real-time data access ## Setup 1. Clone the repository 2. Copy `.env.example` to `.env` and fill in your Salesforce credentials 3. Install dependencies: `npm install` 4. Build: `npm run build` 5. Start: `npm start` ## Usage The server exposes several functions: ### query Execute SOQL queries against your Salesforce instance: ```json { "name": "query", "parameters": { "query": "SELECT Id, Name FROM Account LIMIT 5" } } ``` ### describe-object Get metadata about a Salesforce object: ```json { "name": "describe-object", "parameters": { "objectName": "Account" } } ``` ### create Create a new record: ```json { "name": "create", "parameters": { "objectName": "Contact", "data": { "FirstName": "John", "LastName": "Doe", "Email": "[email protected]" } } } ``` ### update Update an existing record: ```json { "name": "update", "parameters": { "objectName": "Contact", "data": { "Id": "003XXXXXXXXXXXXXXX", "Email": "[email protected]" } } } ``` ### delete Delete a record: ```json { "name": "delete", "parameters": { "objectName": "Contact", "id": "003XXXXXXXXXXXXXXX" } } ``` ## Security Make sure to: - Keep your `.env` file secure and never commit it - Use IP restrictions in Salesforce when possible - Regularly rotate your security token - Consider implementing additional authentication for the MCP server ## Contributing Contributions are welcome! Please submit PRs with improvements. ## License MIT License ``` MIT License Copyright (c) 2024 Kablewy,LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` ``` -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- ```json { "compilerOptions": { "target": "ES2020", "module": "ES2020", "moduleResolution": "bundler", "esModuleInterop": true, "outDir": "./build", "rootDir": "./src", "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "declaration": true }, "include": ["src/**/*"], "exclude": ["node_modules", "build"] } ``` -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- ```json { "name": "salesforce-mcp-server", "version": "1.0.0", "type": "module", "scripts": { "build": "tsc", "start": "node build/index.js", "dev": "tsx watch src/index.ts" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.1", "dotenv": "^16.3.1", "jsforce": "^3.6.3", "mcp-evals": "^1.0.18" }, "devDependencies": { "@types/jsforce": "^1.11.5", "@types/node": "^20.10.4", "tsx": "^4.6.2", "typescript": "^5.7.2" } } ``` -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- ```dockerfile # Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile # Use an official Node.js runtime as a parent image FROM node:18-alpine AS builder # Set the working directory in the container WORKDIR /app # Copy the package.json and package-lock.json files COPY package*.json ./ # Install the dependencies RUN npm install # Copy the rest of the application code COPY . . # Build the TypeScript code RUN npm run build # Use a new, clean Node.js runtime for the final image FROM node:18-alpine # Set the working directory WORKDIR /app # Copy the compiled application and node_modules from the builder stage COPY --from=builder /app/build ./build COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/package.json ./ # Specify the default command to run when starting the container CMD ["npm", "start"] ``` -------------------------------------------------------------------------------- /smithery.yaml: -------------------------------------------------------------------------------- ```yaml # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml startCommand: type: stdio configSchema: # JSON Schema defining the configuration options for the MCP. type: object required: - sfUsername - sfPassword - sfSecurityToken properties: sfUsername: type: string description: Salesforce username. sfPassword: type: string description: Salesforce password. sfSecurityToken: type: string description: Salesforce security token. sfLoginUrl: type: string default: https://login.salesforce.com description: Salesforce login URL. commandFunction: # A function that produces the CLI command to start the MCP on stdio. |- (config) => ({ command: 'npm', args: ['start'], env: { SF_USERNAME: config.sfUsername, SF_PASSWORD: config.sfPassword, SF_SECURITY_TOKEN: config.sfSecurityToken, SF_LOGIN_URL: config.sfLoginUrl || 'https://login.salesforce.com' } }) ``` -------------------------------------------------------------------------------- /src/types.ts: -------------------------------------------------------------------------------- ```typescript import type { MetadataType } from 'jsforce/api/metadata'; // Existing query interface export interface QueryArgs { query: string; } export interface ToolingQueryArgs { query: string; } export interface DescribeObjectArgs { objectName: string; detailed?: boolean; } export interface MetadataRetrieveArgs { type: MetadataType; // Using jsforce's MetadataType fullNames: string[]; } // Type guards export function isValidQueryArgs(args: any): args is QueryArgs { return ( typeof args === "object" && args !== null && "query" in args && typeof args.query === "string" ); } export function isValidToolingQueryArgs(args: any): args is ToolingQueryArgs { return ( typeof args === "object" && args !== null && "query" in args && typeof args.query === "string" ); } export function isValidDescribeObjectArgs(args: any): args is DescribeObjectArgs { return ( typeof args === "object" && args !== null && "objectName" in args && typeof args.objectName === "string" && (args.detailed === undefined || typeof args.detailed === "boolean") ); } export function isValidMetadataRetrieveArgs(args: any): args is MetadataRetrieveArgs { return ( typeof args === "object" && args !== null && "type" in args && typeof args.type === "string" && // We'll validate against MetadataType in the handler "fullNames" in args && Array.isArray(args.fullNames) && args.fullNames.every((name: any) => typeof name === "string") ); } // Helper function to validate MetadataType export function isValidMetadataType(type: string): type is MetadataType { return [ 'CustomObject', 'Flow', 'FlowDefinition', 'CustomField', 'ValidationRule', 'ApexClass', 'ApexTrigger', 'WorkflowRule', 'Layout' // Add more as needed ].includes(type); } ``` -------------------------------------------------------------------------------- /src/evals/evals.ts: -------------------------------------------------------------------------------- ```typescript //evals.ts import { EvalConfig } from 'mcp-evals'; import { openai } from "@ai-sdk/openai"; import { grade, EvalFunction } from "mcp-evals"; const queryEval: EvalFunction = { name: "queryEval", description: "Evaluates the Salesforce query tool functionality", run: async () => { const result = await grade(openai("gpt-4"), "Please execute a SOQL query to retrieve all Contact records from Salesforce and return their names and IDs."); return JSON.parse(result); } }; const toolingQueryEval: EvalFunction = { name: "Tooling Query Evaluation", description: "Evaluates the functionality of executing a query against the Salesforce Tooling API", run: async () => { const result = await grade(openai("gpt-4"), "Please execute a Tooling API query to list all Apex classes in the org."); return JSON.parse(result); } }; const describeObjectEval: EvalFunction = { name: 'describe-object Evaluation', description: 'Evaluates the detailed metadata retrieval for a Salesforce object', run: async () => { const result = await grade(openai("gpt-4"), "Describe the Opportunity object in Salesforce with detailed metadata"); return JSON.parse(result); } }; const metadataRetrieveEval: EvalFunction = { name: "metadata-retrieve Evaluation", description: "Evaluates the functionality of retrieving metadata components from Salesforce", run: async () => { const result = await grade(openai("gpt-4"), "Please retrieve the Flow named 'MyFlow' from Salesforce using your metadata-retrieve tool."); return JSON.parse(result); } }; const queryEval: EvalFunction = { name: 'query Tool Evaluation', description: 'Evaluates the correctness of executing a SOQL query on Salesforce', run: async () => { const result = await grade(openai("gpt-4"), "Use the query tool to retrieve the first ten accounts from Salesforce, returning Id and Name fields."); return JSON.parse(result); } }; const config: EvalConfig = { model: openai("gpt-4"), evals: [queryEval, toolingQueryEval, describeObjectEval, metadataRetrieveEval, queryEval] }; export default config; export const evals = [queryEval, toolingQueryEval, describeObjectEval, metadataRetrieveEval, queryEval]; ``` -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- ```typescript #!/usr/bin/env node import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js"; import * as jsforce from 'jsforce'; import dotenv from "dotenv"; import { tools } from "./tools.js"; dotenv.config(); const API_CONFIG = { LOGIN_URL: process.env.SF_LOGIN_URL || 'https://login.salesforce.com' } as const; if (!process.env.SF_USERNAME || !process.env.SF_PASSWORD || !process.env.SF_SECURITY_TOKEN) { throw new Error("SF_USERNAME, SF_PASSWORD, and SF_SECURITY_TOKEN environment variables are required"); } class SalesforceServer { private server: Server; private conn: jsforce.Connection; constructor() { this.server = new Server({ name: "salesforce-mcp-server", version: "0.2.0" }, { capabilities: { tools: {} } }); this.conn = new jsforce.Connection({ loginUrl: API_CONFIG.LOGIN_URL, version:'58.0' }); this.setupHandlers(); this.setupErrorHandling(); } private setupErrorHandling(): void { this.server.onerror = (error) => { console.error("[MCP Error]", error); }; process.on('SIGINT', async () => { await this.server.close(); process.exit(0); }); } private setupHandlers(): void { this.server.setRequestHandler( ListToolsRequestSchema, async () => ({ tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) }) ); this.server.setRequestHandler( CallToolRequestSchema, async (request) => { const tool = tools.find(t => t.name === request.params.name); if (!tool) { return { content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }], isError: true }; } try { await this.conn.login( process.env.SF_USERNAME!, process.env.SF_PASSWORD! + process.env.SF_SECURITY_TOKEN! ); const result = await tool.handler(this.conn, request.params.arguments); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } catch (error) { return { content: [{ type: "text", text: `Salesforce API error: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } ); } async run(): Promise<void> { const transport = new StdioServerTransport(); await this.server.connect(transport); console.error("Salesforce MCP server running on stdio"); } } const server = new SalesforceServer(); server.run().catch(console.error); ``` -------------------------------------------------------------------------------- /src/tools.ts: -------------------------------------------------------------------------------- ```typescript import { Connection } from 'jsforce'; import { QueryArgs, ToolingQueryArgs, DescribeObjectArgs, MetadataRetrieveArgs, isValidToolingQueryArgs, isValidDescribeObjectArgs, isValidMetadataRetrieveArgs, isValidMetadataType } from './types.js'; export interface ToolHandler { name: string; description: string; inputSchema: Record<string, any>; handler: (conn: Connection, args: any) => Promise<any>; } export const tools: ToolHandler[] = [ { name: "query", description: "Execute a SOQL query on Salesforce", inputSchema: { type: "object", properties: { query: { type: "string", description: "SOQL query to execute" } }, required: ["query"] }, handler: async (conn: Connection, args: QueryArgs) => { return await conn.query(args.query); } }, { name: "tooling-query", description: "Execute a query against the Salesforce Tooling API", inputSchema: { type: "object", properties: { query: { type: "string", description: "Tooling API query to execute" } }, required: ["query"] }, handler: async (conn: Connection, args: ToolingQueryArgs) => { if (!isValidToolingQueryArgs(args)) { throw new Error("Invalid tooling query arguments"); } return await conn.tooling.query(args.query); } }, { name: "describe-object", description: "Get detailed metadata about a Salesforce object", inputSchema: { type: "object", properties: { objectName: { type: "string", description: "API name of the object to describe" }, detailed: { type: "boolean", description: "Whether to return full metadata (optional)", default: false } }, required: ["objectName"] }, handler: async (conn: Connection, args: DescribeObjectArgs) => { if (!isValidDescribeObjectArgs(args)) { throw new Error("Invalid describe object arguments"); } const objType = conn.sobject(args.objectName); if (args.detailed) { // For custom objects, we can get additional metadata if (args.objectName.endsWith('__c')) { const [describe, metadata] = await Promise.all([ objType.describe(), conn.metadata.read('CustomObject', args.objectName) ]); return { describe, metadata }; } return await objType.describe(); } return await objType.describe(); } }, { name: "metadata-retrieve", description: "Retrieve metadata components from Salesforce", inputSchema: { type: "object", properties: { type: { type: "string", description: "Metadata type (e.g., Flow, CustomObject)", enum: [ 'CustomObject', 'Flow', 'FlowDefinition', 'CustomField', 'ValidationRule', 'ApexClass', 'ApexTrigger', 'WorkflowRule', 'Layout' ] }, fullNames: { type: "array", items: { type: "string" }, description: "Array of component names to retrieve" } }, required: ["type", "fullNames"] }, handler: async (conn: Connection, args: MetadataRetrieveArgs) => { if (!isValidMetadataRetrieveArgs(args)) { throw new Error("Invalid metadata retrieve arguments"); } if (!isValidMetadataType(args.type)) { throw new Error(`Invalid metadata type: ${args.type}`); } return await conn.metadata.read(args.type, args.fullNames); } } ]; ```