DEV Community: Sudhakar

The 'Disconnected' Dilemma: A Mac User's Journey to Connecting the Gemini CLI and Salesforce MCP server

Sudhakar — Mon, 27 Oct 2025 04:59:10 +0000

🧩 The "Disconnected" Dilemma: A Mac User’s Journey to Connecting the Gemini CLI and Salesforce

Connecting the Gemini CLI to Salesforce felt like unlocking a superpower — using natural language to query orgs, analyze code, and deploy metadata, all from the terminal.

But what I thought would be a 10-minute setup turned into a multi-step troubleshooting puzzle.

The main villain?

🔴 salesforce - Disconnected

This is the story of that journey, the problems I faced on Mac (Apple Silicon), and the “Aha!” moment that finally fixed it.

If you’re seeing that same red dot, this guide is for you.

🎯 The Goal & The Setup

The Goal: Configure the Gemini CLI to use the Salesforce MCP Server.

The Machine: A Mac with Apple Silicon (M1/M2/M3).

🧰 The Key Software

Gemini CLI – The AI agent.
Salesforce CLI (sf) – Installed and authorized with a default org.
npm / npx – Used to run the MCP server package.

🧪 The Troubleshooting Timeline

Phase 1: The “By the Book” Attempt (And the First Failure)

I started by following the developer documentation. It suggested using the Salesforce CLI directly to start the server.

My ~/.gemini/settings.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "sf",
      "args": ["force", "mcp:server:start"]
    }
  }
}

The Result:
I launched Gemini and ran:

bash /mcp list

The Output:

✗ salesforce: ... - Disconnected

The command seemed logical but clearly wasn’t establishing the persistent connection Gemini needed.

Phase 2: Finding the Right Package (And a New Mystery)

After more research, I found that the standard way to run the server is by using the dedicated npm package @salesforce/mcp.

My ~/.gemini/settings.json (Attempt 2):

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

The Result:
After restarting Gemini and running /mcp list:

✗ salesforce: npx -y @salesforce/mcp ... - Disconnected

This was frustrating. The command was correct, the package official, and the org authorized. So why was it still disconnecting?

Phase 3: The “Aha!” Moment (Testing the Command Directly)

We realized we were assuming the command itself was failing.
But what if Gemini was the one failing to connect?

The Test:
Run the command directly in the terminal:

bash npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,code-analysis

The Result:

Salesforce MCP Server v0.23.4 running on stdio

✅ The server worked perfectly.
The Salesforce CLI authorization and npx command were fine.
The issue wasn’t Salesforce — it was how Gemini was spawning the process.

Phase 4: The Mac Silicon Clue (Environment Mismatch)

Here’s where the Apple Silicon clue came in.

When Gemini (a Node.js app) spawns a child process (like npx), it doesn’t always inherit the full $PATH from your interactive shell (like .zshrc).
This happens frequently when using version managers like nvm or fnm.

Gemini was trying to run npx, but its isolated environment couldn’t find the command.
The process exited instantly, and Gemini reported Disconnected.

Phase 5: The Fix (Absolute Path to the Rescue)

If the $PATH is unreliable, don’t rely on it.
Tell Gemini exactly where npx lives.

Step 1: Find the Path

bash which npx

Example output:

/usr/local/bin/npx

Yours might differ, such as /Users/<your-name>/.nvm/versions/node/v20.x.x/bin/npx.

Step 2: Update settings.json

Final, working version:

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

Phase 6: Success!

After saving the file and relaunching Gemini, I ran:

bash /mcp list

The Output:

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

It finally connected 🎉

⚙️ Now What? How to Use Your Connected Server

Getting Connected is just the first step.
Next, you need to use the available tools through natural language.

You don’t explicitly tell Gemini which tool to use — it infers that based on your prompt.

💬 How to Prompt Gemini

Use descriptive keywords that align with the tools (deploy_metadata, retrieve_metadata, code-analysis, etc.).

Examples:

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.”

Each time, Gemini asks for confirmation and shows the exact command it plans to execute — proof that the MCP server is being used.

📚 Appendix: Installation & Useful Links

🧩 1. Running via npx (Standard Method)

bash npx -y @salesforce/mcp@latest --orgs DEFAULT_TARGET_ORG --toolsets orgs,metadata,data,users

What it does:
Downloads and runs the latest MCP package, then removes it.
Perfect for testing.

🧰 2. Installing Globally (Optional Troubleshooting Step)

If npx is unreliable, you can install globally:

bash npm install -g @salesforce/mcp

This ensures a stable global package version.
Not required for most users, but helpful if npx caching fails.

🔗 Related Documentation

💡 Key Lessons for Future Users

"Disconnected" = "Instant Exit" → The server process likely failed to start.
Test Commands Directly → Always run the command + args outside Gemini first.
Mac/Linux Users (especially with nvm/fnm): Use the absolute path to npx or other executables.
Windows Users: Use "cmd" with "/c" in settings.json, e.g.:

json "command": "cmd", "args": ["/c", "npx", ...]

🏁 Conclusion:
The “Disconnected” message wasn’t a bug — it was a clue.
Understanding how Gemini spawns its processes revealed the real issue: environment inheritance.
With the absolute path fix, the Gemini–Salesforce bridge now runs perfectly.

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

Sudhakar — Mon, 27 Oct 2025 04:52:37 +0000

⚙️ 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

Prerequisites
Step 1: Find Your settings.json File
Step 2: Get the Server Command (The Gotcha & Fix)
- macOS & Linux Users
- Windows Users
Step 3: Configure Your settings.json
- macOS / Linux Configuration
- Windows Configuration
Step 4: Verify the Connection
Step 5: Use the Connected Server
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

/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.

Syncing two Git Repos (By using below commands you can move contents of one git repo to another without losing history and tags)

Sudhakar — Sat, 10 Aug 2019 17:32:04 +0000

Cloning SourceRepo and Pushing that to TargetRepo

git clone --mirror SourceRepoURL

The above git clone command will create a directory in your local machine with the name of your repo.

Change to that directory and add a remote to the target repo.

cd SourceRepo
git remote add NEW-REMOTE TargetRepoURL
It creates a connection with TargetRepo.
Here'NEW-REMOTE' is just a name, you can give your own Name. Remember that name to sync these two repos.

git push NEW-REMOTE --mirror
It will push all folders and history of Source repo to Target Repo.

Syncing Those two Repos

After cloning source and pushing to target if you make any more changes to source simply use below two commands from the same directory to sync.

git fetch origin
To pull SourceRepo changes

git push NEW-REMOTE --all
To push(sync) SourceRepo changes to TargetRepo.

DEV Community: Sudhakar

The 'Disconnected' Dilemma: A Mac User's Journey to Connecting the Gemini CLI and Salesforce MCP server

🧩 The "Disconnected" Dilemma: A Mac User’s Journey to Connecting the Gemini CLI and Salesforce

🎯 The Goal & The Setup

🧰 The Key Software

🧪 The Troubleshooting Timeline

Phase 1: The “By the Book” Attempt (And the First Failure)

Phase 2: Finding the Right Package (And a New Mystery)

Phase 3: The “Aha!” Moment (Testing the Command Directly)

Phase 4: The Mac Silicon Clue (Environment Mismatch)

Phase 5: The Fix (Absolute Path to the Rescue)

Phase 6: Success!

⚙️ Now What? How to Use Your Connected Server

💬 How to Prompt Gemini

📚 Appendix: Installation & Useful Links

🧩 1. Running via npx (Standard Method)

🧰 2. Installing Globally (Optional Troubleshooting Step)

🔗 Related Documentation

💡 Key Lessons for Future Users

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

📑 Table of Contents

🧰 Prerequisites

🏠 Step 1: Find Your settings.json File

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

For macOS & Linux Users

For Windows Users

🧾 Step 3: Configure Your settings.json

💻 Final Configuration for macOS / Linux

🪟 Final Configuration for Windows

✅ Step 4: Verify the Connection

🚀 Step 5: How to Use Your Connected Server

Example Prompts

📚 Appendix: Installation & Useful Links

How to Install the Salesforce MCP Server

🔗 Official Documentation

Syncing two Git Repos (By using below commands you can move contents of one git repo to another without losing history and tags)

🏠 Step 1: Find Your `settings.json` File

🧾 Step 3: Configure Your `settings.json`