Skip to main content
Glama
tomnagengast

mcp-server-salesforce

by tomnagengast
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Salesforce MCP Server

A Model Context Protocol (MCP) server that provides AI agents with secure access to Salesforce data and operations. Built for sales, marketing, and executive teams to interact with their Salesforce CRM through natural language.

Features

Core Capabilities

  • šŸ” Search & Query: Search records across multiple objects, execute SOQL queries, and perform global searches

  • šŸ“– Read Operations: Retrieve specific records and navigate relationships

  • šŸ”’ Security-First: Starts in read-only mode by default for safe testing

  • šŸ” Secure Authentication: OAuth 2.0 integration with proper token management

  • āš” Error Handling: Comprehensive error handling with detailed feedback

Safety Features

  • Read-Only by Default: Server starts in safe read-only mode

  • Configurable Write Access: Enable write operations only when ready with SALESFORCE_READ_ONLY_MODE=false

  • Clear Operation Indicators: Write tools clearly marked in descriptions

Supported Salesforce Objects

  • Accounts: Company and organization records

  • Contacts: Individual contact information

  • Leads: Prospective customer records

  • Opportunities: Sales pipeline and deals

  • Cases: Customer service and support tickets

  • Activities: Tasks and events

Related MCP server: MCP Salesforce Server

Quick Start

šŸš€ For complete setup instructions, see SETUP.md

This includes:

  • Salesforce Connected App configuration

  • Claude Desktop integration

  • Step-by-step screenshots and troubleshooting

Installation Options

Option 1: NPX from GitHub

npx github:tomnagengast/mcp-server-salesforce

Option 2: Clone and Build

git clone https://github.com/tomnagengast/mcp-server-salesforce.git
cd mcp-server-salesforce
npm install
npm run build

Configuration: See SETUP.md for complete setup instructions including Salesforce Connected App configuration.

Configuration

Environment Variables

Create a .env file with the following configuration:

# Salesforce Configuration
SALESFORCE_LOGIN_URL=https://login.salesforce.com
SALESFORCE_CLIENT_ID=your_connected_app_client_id
SALESFORCE_CLIENT_SECRET=your_connected_app_client_secret
SALESFORCE_USERNAME=your_salesforce_username
SALESFORCE_PASSWORD=your_salesforce_password
SALESFORCE_SECURITY_TOKEN=your_security_token

# For Sandbox (optional)
# SALESFORCE_LOGIN_URL=https://test.salesforce.com

# Server Configuration
PORT=3000
LOG_LEVEL=info

# Security - Server starts in READ-ONLY mode by default
SALESFORCE_READ_ONLY_MODE=true

šŸ”’ Security Note: The server starts in read-only mode by default. Set SALESFORCE_READ_ONLY_MODE=false only when you're comfortable with write operations.

Claude Desktop Integration

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

For NPX installation:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["github:tomnagengast/mcp-server-salesforce"],
      "env": {
        "SALESFORCE_CLIENT_ID": "your_client_id",
        "SALESFORCE_CLIENT_SECRET": "your_client_secret",
        "SALESFORCE_USERNAME": "your_username", 
        "SALESFORCE_PASSWORD": "your_password",
        "SALESFORCE_SECURITY_TOKEN": "your_token",
        "SALESFORCE_READ_ONLY_MODE": "true"
      }
    }
  }
}

For local installation:

{
  "mcpServers": {
    "salesforce": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-salesforce/dist/index.js"],
      "cwd": "/path/to/your/mcp-server-salesforce"
    }
  }
}

See SETUP.md for complete integration instructions.

Usage

Running the Server

# Development mode with hot reload
npm run dev

# Production mode
npm run start

Available Tools

Search Tools

search_records - Search across multiple Salesforce objects

{
  "query": "Acme Corp",
  "objects": ["Account", "Contact", "Lead"],
  "limit": 20
}

soql_query - Execute custom SOQL queries

{
  "query": "SELECT Id, Name, Email FROM Contact WHERE Account.Name = 'Acme Corp'"
}

global_search - Global search across all objects

{
  "searchTerm": "john@example.com",
  "limit": 20
}

Read Operations (Always Available)

get_record - Retrieve a specific record

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "fields": ["Name", "Type", "Industry"]
}

get_related_records - Get related records

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "relationship": "Contacts",
  "limit": 20
}

get_record_history - View field history

{
  "objectType": "Opportunity",
  "recordId": "006XXXXXXXXXX",
  "limit": 20
}

Write Operations (Requires SALESFORCE_READ_ONLY_MODE=false)

āš ļø These operations modify your Salesforce data. Only enable when you're comfortable with the server's behavior.

create_record - Create a new record

{
  "objectType": "Contact",
  "data": {
    "FirstName": "John",
    "LastName": "Doe",
    "Email": "john@example.com"
  }
}

update_record - Update an existing record

{
  "objectType": "Account",
  "recordId": "001XXXXXXXXXX",
  "data": {
    "Phone": "+1-555-0123"
  }
}

delete_record - Delete a record

{
  "objectType": "Lead",
  "recordId": "00QXXXXXXXXXX"
}

Enabling Write Operations

When you're ready to enable write operations:

  1. Update environment:

    # In your .env file
SALESFORCE_READ_ONLY_MODE=false

  2. Or in Claude Desktop config:

    {
  "mcpServers": {
    "salesforce": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-salesforce/dist/index.js"],
      "env": {
        "SALESFORCE_READ_ONLY_MODE": "false",
        // ... other env vars
      }
    }
  }
}

  3. Restart the server and Claude Desktop

Use Cases

Sales Team

  • Pipeline Management: "Show me all opportunities closing this quarter"

  • Account Research: "Find all contacts at Acme Corp with their recent activities"

  • Lead Follow-up: "Find all leads from yesterday's trade show" (read-only) or "Create tasks for all leads from yesterday's trade show" (write mode)

Marketing Team

  • Campaign Analysis: "Show ROI for Q4 digital campaigns"

  • Lead Scoring: "Find high-score leads that haven't been contacted"

  • Content Performance: "Which campaigns generated the most qualified leads?"

Executive Team

  • Revenue Forecasting: "What's our pipeline by region for next quarter?"

  • Performance Metrics: "Show top performers by closed revenue this month"

  • Customer Health: "List top 20 accounts and their recent engagement"

Development

Scripts

npm run build      # Build TypeScript
npm run dev        # Development with hot reload
npm run start      # Start production server
npm run lint       # Run ESLint
npm run test       # Run tests (when implemented)

Project Structure

src/
ā”œā”€ā”€ auth/              # Salesforce authentication
ā”œā”€ā”€ tools/             # MCP tool implementations
ā”‚   ā”œā”€ā”€ search-tools.ts    # Search and query tools
ā”‚   ā”œā”€ā”€ crud-tools.ts      # CRUD operations
ā”‚   ā””ā”€ā”€ relationship-tools.ts # Relationship navigation
ā”œā”€ā”€ types/             # TypeScript type definitions
ā”œā”€ā”€ utils/             # Utilities and helpers
ā”‚   ā”œā”€ā”€ config.ts          # Configuration management
ā”‚   ā”œā”€ā”€ logger.ts          # Logging utilities
ā”‚   ā””ā”€ā”€ error-handler.ts   # Error handling
ā””ā”€ā”€ index.ts           # Main server entry point

Security

  • OAuth 2.0: Secure authentication with Salesforce

  • Permission Respect: All operations respect Salesforce user permissions

  • Input Validation: SOQL injection prevention and input sanitization

  • Error Handling: Secure error messages without sensitive data exposure

Troubleshooting

Common Issues

Authentication Failed

  • Verify your Salesforce credentials

  • Check if your IP is allowlisted in Salesforce

  • Ensure the security token is current

Permission Denied

  • Verify user has appropriate object permissions

  • Check field-level security settings

  • Ensure profile has API access enabled

API Limits

  • Monitor API usage in Salesforce Setup

  • Implement rate limiting if needed

  • Consider using bulk operations for large datasets

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run tests and linting

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Available Tools

6 tools
get_recordB

Retrieve a specific Salesforce record by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNoFields to retrieve (optional, defaults to common fields)
recordIdYesSalesforce record ID
objectTypeYesSalesforce object type (e.g., Account, Contact)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'retrieve', implying a read operation, but does not confirm non-destructiveness, authentication needs, rate limits, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 8 words, front-loaded with the key action and resource. Every word is necessary, with zero redundancy or irrelevance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is incomplete. It does not specify the return format (e.g., full record object, specific fields), error handling, or what happens if the ID is invalid.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters have descriptions. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a specific Salesforce record by ID, using a specific verb and resource. It distinguishes itself from sibling tools like search_records, soql_query, and global_search by focusing on single-record retrieval by ID.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool vs alternatives (e.g., search_records for filtering, soql_query for complex queries). No when-not-to-use or exclusion criteria are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_record_historyB

Get the field history for a record

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of history records
recordIdYesRecord ID
objectTypeYesObject type

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavior. It does not mention that the tool is read-only, any required permissions, or the scope of history returned. The limit parameter is documented in schema but not explained in behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and to the point. It is not verbose, but could benefit from a bit more context without being overly long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema and annotations, the description is minimally complete. It does not describe the return format, pagination, or what 'field history' includes. The schema covers the parameters, but the overall behavior is under-specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for all three parameters, so the description adds no extra meaning. The descriptions in the schema already cover objectType, recordId, and limit. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'field history for a record', which distinguishes it from sibling tools like get_record (current data) or search_records (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as get_record or search_records. The context of history retrieval is implied but not explicitly compared.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_recordsC

Search for Salesforce records across multiple objects

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of records to return
queryYesSearch query string
objectsNoObject types to search (e.g., Account, Contact, Lead)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description should disclose behavioral traits. The minimal description does not mention whether the search is read-only, performance implications, or query syntax details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and front-loaded. It earns its place but could be expanded slightly without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description is incomplete. It does not explain return format, pagination, or error handling, which is required given the complexity of searching across multiple objects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters adequately. The description adds no additional meaning beyond the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches across multiple objects, which is a specific verb+resource. However, it does not differentiate from sibling tools like soql_query or global_search, which also search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like soql_query or global_search. The description lacks context on preferred use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

soql_queryB

Execute a SOQL query against Salesforce (read-only)

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSOQL query string (SELECT statements only)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It only discloses that the operation is read-only, but lacks details on performance limits, row limits, error handling, or idempotency, leaving significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and to the point, with no wasted words. It is front-loaded with the key action and resource. However, slightly more structure could improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description should provide more context about return format, error cases, and query restrictions (e.g., object or row limits). The current description is too minimal for a tool that may have complex behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter info (SOQL query string, SELECT statements) from the schema without adding new semantic value, contributing no extra clarity beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Execute', the resource 'SOQL query', and the target 'Salesforce', with the read-only constraint. It effectively distinguishes this tool from siblings like search_records and global_search by specifying it's for SOQL queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for SOQL queries but does not explicitly state when to use this tool over alternatives, such as for complex queries versus simple record retrieval. There is no mention of exclusions or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observedget_record
    • First observedget_record_history
    • First observedget_related_records
    • First observedglobal_search
    • First observedsearch_records
    • First observedsoql_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 6 tools

Disambiguation3/5

Tools like search_records and global_search have overlapping purposes, both searching across objects. Their descriptions do not clearly differentiate them, causing potential confusion for an agent.

Naming Consistency4/5

Most tool names follow a verb_noun pattern (e.g., get_record, search_records), but global_search is noun_verb, and soql_query is a slight deviation. Overall, the pattern is mostly consistent.

Tool Count5/5

With 6 tools, the server is well-scoped for read-only Salesforce operations. Each tool serves a clear purpose without redundancy, and the count is appropriate for the domain.

Completeness2/5

The tool set covers only read operations (queries and retrievals). Missing create, update, delete, and metadata discovery tools create significant gaps for typical Salesforce workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Salesforce Lite

    luvl
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to securely interact with Salesforce CRM data through SOQL queries, CRUD operations, and metadata exploration. Supports connecting to Salesforce objects like Accounts, Contacts, and Opportunities via OAuth 2.0 authentication.
    8
    2
    MIT

  • MCP Salesforce Server

    AiondaDotCom
    A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to interact with Salesforce through a secure interface for performing CRUD operations, executing SOQL queries, and managing schema discovery. It features a smart learning system that analyzes custom objects and fields to provide intelligent assistance tailored to specific Salesforce configurations.
    14
    50 npm
    17
    BSD 2-Clause "Simplified"

  • Salesforce MCP Server

    mintmcp
    A
    license
    A
    quality
    B
    maintenance
    Enables interaction with Salesforce orgs to perform operations like querying data with SOQL, managing records, and executing Apex code. It provides configurable access levels and support for both standard and Tooling APIs via natural language interfaces.
    11
    MIT

  • Salesforce MCP Server

    aaronsb
    A
    license
    B
    quality
    A
    maintenance
    Enables AI-powered interaction with Salesforce, providing opportunity intelligence, engagement analysis, business case generation, and standard CRUD operations through natural language.
    18
    50 npm
    5
    MIT