This Salesforce MCP Server provides standardized tools for interacting with Salesforce data and metadata through Claude Desktop and other MCP clients.
Key Capabilities:
Run SOQL queries - Execute queries and return structured JSON results with records and total size
List and describe Salesforce objects - Get all available SObjects in your organization and retrieve detailed field information including types, labels, nillable status, and picklist values
Manage Salesforce flows - List all flows with status/version information and retrieve complete XML metadata for specific flows
Access reports and dashboards - List all Salesforce reports and dashboards with their folder and usage information
Provides tools for querying Salesforce data using SOQL, listing all Salesforce objects in an org, and describing detailed field information for any Salesforce object through the sf CLI.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Salesforce MCP Server show me all active accounts with their owners"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This server provides MCP (Model Context Protocol) tools for interacting with Salesforce using the sf CLI. It exposes Salesforce data and metadata through standardized MCP tools that can be used with Claude Desktop and other MCP clients.
Query Tool (salesforce_query) - Run SOQL queries and return structured results
List Objects (salesforce_list_objects) - Get all Salesforce object names in your org
Describe Objects (salesforce_describe) - Get detailed field information for any Salesforce object
List Flows (salesforce_list_flows) - Get all Salesforce flows with status and version information
Describe Flow (salesforce_describe_flow) - Get the complete XML metadata for a specific flow
List Reports (salesforce_list_reports) - Get all Salesforce reports with folder and usage information
List Dashboards (salesforce_list_dashboards) - Get all Salesforce dashboards with folder and usage information
Related MCP server: Salesforce MCP Server
Before running the configuration script, you must install these prerequisites:
macOS (this setup is optimized for macOS, but should work on Linux/Windows)
Python 3.11+ - Required for running the MCP server
Poetry - Python dependency management
Node.js - Required for Salesforce CLI
Salesforce CLI - Command line interface for Salesforce
1. Python 3.11+
# macOS (via Homebrew)
brew install python@3.11
# Or download directly from Python.org
# https://www.python.org/downloads/2. Poetry
# Install Poetry (official installer)
curl -sSL https://install.python-poetry.org | python3 -
# Verify installation
poetry --version3. Node.js
# macOS (via Homebrew)
brew install node
# Or download from Node.js website
# https://nodejs.org/4. Salesforce CLI
# Install via npm (requires Node.js)
npm install -g @salesforce/cli
# Verify installation
sf --versionRun these commands to verify all prerequisites are installed:
python3 --version # Should be 3.11+
poetry --version # Should show Poetry version
node --version # Should show Node version
sf --version # Should show Salesforce CLI versionQuick Start (after installing prerequisites):
git clone https://github.com/mattmahowald/sfmcp.git
cd sfmcp
./install.py # Configures SFMCP for your Salesforce orgThe configuration script will:
✅ Check all prerequisites are installed
📦 Install Python dependencies via Poetry
🔐 Authenticate with your Salesforce org (or select existing auth)
⚙️ Create .env configuration file
🖥️ Update Claude Desktop configuration
Prerequisites must be installed first - see the Prerequisites section above.
If you prefer to set up manually:
Install prerequisites (see Prerequisites section above)
Install Python dependencies:
poetry installAuthenticate with Salesforce:
sf org login webCreate .env file with your Salesforce org details:
SF_INSTANCE_URL=https://your-org.my.salesforce.com
SF_ACCESS_TOKEN=your-access-token
SF_ORG_ALIAS=your-org-alias
SF_USERNAME=your-usernameConfigure Claude Desktop by adding this to your claude_desktop_config.json:
{
"mcpServers": {
"sfmcp": {
"command": "/path/to/your/sfmcp/run-mcp.sh",
"args": []
}
}
}Restart Claude Desktop to load the new MCP server.
Once configured, you can use these tools in Claude Desktop conversations:
"List all Salesforce objects" - Uses salesforce_list_objects
"Describe the Account object" - Uses salesforce_describe
"Query all active accounts" - Uses salesforce_query
"List all flows" - Uses salesforce_list_flows
"Describe the Contact_Last_Reply_Date flow" - Uses salesforce_describe_flow
"List all reports" - Uses salesforce_list_reports
"List all dashboards" - Uses salesforce_list_dashboards
Example queries:
SELECT Id, Name FROM Account LIMIT 10
SELECT Id, Email FROM Contact WHERE Email != null
STDIO Mode (for MCP clients):
poetry run sfmcp-stdio
# or
./scripts/run_stdio.shHTTP Mode (for testing):
poetry run sfmcp-http
# or
./scripts/run_http.sh# Type checking
poetry run mypy sfmcp/
# Linting
poetry run ruff check sfmcp/
# Formatting
poetry run ruff format sfmcp/The server uses environment variables from .env file:
SF_INSTANCE_URL - Your Salesforce instance URL
SF_ACCESS_TOKEN - Salesforce access token (automatically managed)
SF_ORG_ALIAS - Alias for your Salesforce org
SF_USERNAME - Your Salesforce username
SFMCP_HTTP_HOST - HTTP server host (default: 127.0.0.1)
SFMCP_HTTP_PORT - HTTP server port (default: 3333)
"Prerequisites check failed"
Install missing prerequisites using the commands in the Prerequisites section
Verify installations with: python3 --version, poetry --version, node --version, sf --version
"Salesforce CLI not found"
Install Salesforce CLI: npm install -g @salesforce/cli
Verify Node.js is installed: node --version
"Authentication failed"
Run sf org list to check authenticated orgs
Re-authenticate: sf org login web
Re-run the configuration script: python install.py
"Permission denied"
Make sure you have proper Salesforce org permissions
Check that your access token hasn't expired
Try re-authenticating with sf org login web
"Poetry not found"
Install Poetry: curl -sSL https://install.python-poetry.org | python3 -
Add to PATH if needed: export PATH="$HOME/.local/bin:$PATH"
Restart your terminal and try again
Describe an SObject and return field information
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
| Name | Required | Description |
|---|---|---|
| fields | Yes | |
| object_api_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns field information, which implies a read-only operation, but doesn't clarify permissions, rate limits, error handling, or what 'Describe' entails beyond the output. For a tool with zero annotation coverage, this is inadequate, scoring 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and outcome, making it easy to parse. Every word earns its place, scoring 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (describing Salesforce objects), the description is minimal but functional. The presence of an output schema reduces the need to explain return values in the description. However, with no annotations and low parameter coverage, it lacks details on usage and behavior, making it barely adequate, scoring 3.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, meaning the parameter 'args' is undocumented in the schema. The description adds no information about parameters, such as what 'args' should contain or how to specify the SObject. It fails to compensate for the low schema coverage, scoring 2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Describe') and resource ('an SObject'), specifying what the tool does. It distinguishes from sibling tools like 'salesforce_list_objects' (which lists objects) and 'salesforce_query' (which queries data) by focusing on metadata/field information. However, it doesn't explicitly mention the sibling differentiation, keeping it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 versus alternatives like 'salesforce_list_objects' or 'salesforce_query'. It doesn't specify prerequisites, context, or exclusions, leaving the agent to infer usage based on tool names alone. This is minimal guidance, scoring 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get list of all Salesforce object names (SObjects)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| total_count | Yes | Total number of objects |
| object_names | Yes | List of Salesforce object names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it 'gets' a list, implying a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, pagination, or what the output includes (e.g., format, sorting). This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy to understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. However, with no annotations and an output schema, it doesn't explain return values or behavioral context, leaving gaps in completeness for a read operation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add param info, but with no params, a baseline of 4 is appropriate as it doesn't need to compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 'list of all Salesforce object names (SObjects)', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'salesforce_describe' or 'salesforce_query', which likely provide more detailed object metadata or query capabilities, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention contexts like needing a high-level overview vs. detailed metadata or querying, and there are no exclusions or prerequisites stated, leaving usage unclear relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a SOQL query and return JSON rows
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
| Name | Required | Description |
|---|---|---|
| records | Yes | |
| total_size | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the basic action and output format. It lacks critical behavioral details: whether this is read-only or mutative, authentication requirements, rate limits, error handling, or pagination for large result sets. The description is minimal and doesn't compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and outcome, making it easy to parse. Every word earns its place, though it may be overly concise given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (executing queries in Salesforce), no annotations, and 0% schema coverage, the description is incomplete. However, the presence of an output schema mitigates the need to explain return values. The description covers the basic purpose but lacks sufficient context for safe and effective use without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter information beyond implying 'args' is for the query. It doesn't explain what 'QueryArgs' contains (e.g., query string, filters), syntax examples, or constraints. The description fails to compensate for the low schema coverage, leaving parameters largely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Run') and resource ('SOQL query') with the outcome ('return JSON rows'). It distinguishes from siblings like 'salesforce_describe' and 'salesforce_list_objects' by focusing on query execution rather than metadata operations. However, it doesn't specify what type of data the query targets (e.g., objects, records).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'salesforce_describe' or 'salesforce_list_objects'. The description implies it's for executing queries but doesn't specify scenarios, prerequisites, or exclusions. The agent must infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0salesforce_describesalesforce_list_objectssalesforce_queryScored across 3 tools
Each tool has a clearly distinct purpose with no overlap: describe provides metadata for a specific object, list_objects enumerates all available objects, and query executes data retrieval. An agent can easily differentiate between these three functions.
All tools follow a consistent snake_case pattern with a 'salesforce_' prefix and clear verb_noun structure (describe, list_objects, query). This uniformity makes the tool set predictable and easy to understand.
With only 3 tools, the server feels thin for a Salesforce integration, lacking essential CRUD operations like create, update, or delete. While the tools cover metadata and querying, the absence of data manipulation limits its utility for typical agent workflows.
The tool surface is severely incomplete for a Salesforce domain, missing core operations such as inserting, updating, or deleting records. Agents will hit dead ends when trying to perform basic data modifications, making this server inadequate for comprehensive Salesforce interactions.
Run SOQL queries to explore and retrieve Salesforce data. Access accounts, contacts, opportunities…
Run SOQL queries against your Salesforce org to retrieve records and insights. Explore objects, fi…
Run SOQL queries to explore and retrieve Salesforce data. Inspect records, fields, and relationshi…
Run SOQL queries against your Salesforce org to explore and retrieve data. Quickly iterate on filt…