Salesforce MCP Server for Gemini CLI (Mac, Linux, Windows)

⚙️ Configuring the Salesforce MCP Server for Gemini CLI

🧭 Hands-On Guide for macOS, Linux, and Windows

Connecting the Gemini CLI to the Salesforce MCP Server unlocks a powerful workflow — allowing you to query orgs, analyze code, and deploy metadata using natural language.

However, many users — especially on macOS with Apple Silicon — immediately encounter a frustrating

🔴 salesforce - Disconnected error.

This guide walks you through the correct, stable configuration to get you up and running.

💡 Root cause: usually an environment $PATH issue.

The fix: explicitly define the full command path Gemini should run.

---

📑 Table of Contents

1. Prerequisites
2. Step 1: Find Your settings.json File
3. Step 2: Get the Server Command (The Gotcha & Fix)
   • macOS & Linux Users
   • Windows Users
4. Step 3: Configure Your settings.json
   • macOS / Linux Configuration
   • Windows Configuration
5. Step 4: Verify the Connection
6. Step 5: Use the Connected Server
7. Appendix: Installation & Useful Links

---

🧰 Prerequisites

Before you begin, ensure you have the following installed and configured:

• Gemini CLI – Google’s AI agent for your terminal
• Salesforce CLI (sf) – The standard Salesforce command-line tool
• Node.js / npm / npx – The Node.js runtime and package manager
• Authorized Salesforce Org – You must have an org authorized and set as default in Salesforce CLI

Authorize an org:

sf org login web

`

Or set an existing org as default:

bash
sf config set target-org <your-org-alias>


---

🏠 Step 1: Find Your settings.json File

Gemini CLI uses a configuration file named settings.json, located in your home directory.
This file tells Gemini how to start the Salesforce server.

Location:


~/.gemini/settings.json


If this file or directory doesn’t exist, create them manually.

---

🧩 Step 2: Get the Server Command (The Gotcha & Fix)

When Gemini starts an MCP server, it launches a child process.
This process might not inherit your shell’s full $PATH, especially on macOS/Linux when using Node version managers like nvm or fnm.

If your settings.json command is simply "npx", Gemini won’t find it — causing the Disconnected error.

✅ Fix: provide the absolute path to your npx executable.

---

For macOS & Linux Users

Run this command outside Gemini:

bash
which npx


Example outputs:


/usr/local/bin/npx


or


/Users/your-name/.nvm/versions/node/v20.x.x/bin/npx


Use this exact path in your configuration.

---

For Windows Users

On Windows, npx must be invoked through the command interpreter.

• Command: "cmd"
• First argument: "/c"

---

🧾 Step 3: Configure Your settings.json

Open the file:


~/.gemini/settings.json


Then add the mcpServers block according to your OS.

---

💻 Final Configuration for macOS / Linux

json
{
"mcpServers": {
"salesforce": {
"command": "/usr/local/bin/npx",
"args": [
"-y",
"@salesforce/mcp@latest",
"--orgs",
"DEFAULT_TARGET_ORG",
"--toolsets",
"orgs,metadata,code-analysis",
"--tools",
"deploy_metadata,retrieve_metadata"
]
}
}
}


💡 Replace "DEFAULT_TARGET_ORG" with your Salesforce org alias (e.g., "my-sandbox-alias").

---

🪟 Final Configuration for Windows

json
{
"mcpServers": {
"salesforce": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@salesforce/mcp@latest",
"--orgs",
"DEFAULT_TARGET_ORG",
"--toolsets",
"orgs,metadata,code-analysis",
"--tools",
"deploy_metadata,retrieve_metadata"
]
}
}
}


---

✅ Step 4: Verify the Connection

Save your configuration and restart Gemini CLI.
Then run:

bash
/mcp list


Expected output:


✓ salesforce: /usr/local/bin/npx -y @salesforce/mcp ... (stdio) - Connected


---

🚀 Step 5: How to Use Your Connected Server

You don’t need to explicitly tell Gemini to “use the Salesforce server.”
Just write prompts describing what you want done — Gemini automatically routes them to the right MCP tools.

Example Prompts

Retrieve Metadata

“Please retrieve the metadata for the Account object from my default Salesforce org.”

Deploy Metadata

“Take the file src/classes/MyNewClass.cls and deploy it to Salesforce.”

Code Analysis

“Analyze the Apex class MyController.cls for any security vulnerabilities or performance issues.”

💬 When you run such prompts, Gemini will ask for confirmation before executing — confirming your MCP server is working correctly.

---

📚 Appendix: Installation & Useful Links

How to Install the Salesforce MCP Server

The setup uses npx to dynamically fetch and run the MCP package.

Standard method:

bash
npx -y @salesforce/mcp ...


This command:

• Downloads the latest @salesforce/mcp package
• Runs it with your arguments (--orgs, --toolsets)
• Removes it after execution

Optional (for troubleshooting):

bash
npm install -g @salesforce/mcp


Installing globally may help if npx fails to find or cache the package properly.

---

🔗 Official Documentation

• 🧭 Salesforce DX MCP Server and Tools (Beta)
  Official developer guide describing MCP server functionality and tools.

• 💻 Salesforce MCP Server GitHub Repository
  Source code and community issue tracker.

---

🏁 You’re all set!
Your Gemini CLI is now successfully connected to the Salesforce MCP Server — ready to analyze, query, and deploy with AI assistance.