@brightfox/sf-mcp-setup

SFDX CLI plugin to configure Salesforce MCP (Model Context Protocol) for Claude Desktop, Cursor, and other MCP clients.

Version 0.3.3 - Cross-platform support with workspace directory configuration.

Quick Start

Install the plugin:

sf plugins install @brightfox/sf-mcp-setup

One-liner setup for Claude Desktop:

sf mcp setup --target-org myOrg --mcp-servers dx --configure-client claude-desktop --workspace-dir default

Then restart Claude Desktop (Cmd+Q on macOS) and you're ready to go!

Installation

# From npm (recommended)
sf plugins install @brightfox/sf-mcp-setup

# From source (development)
git clone https://bitbucket.org/brightfox/sf-mcp-setup.git
cd sf-mcp-setup
npm install && npm run build
sf plugins link .

Usage

Interactive Setup

sf mcp setup --target-org myOrg

This will prompt you for:

• Which MCP servers to enable (DX, Hosted CRM)
• Whether to auto-configure Claude Desktop or Cursor
• Client types for Hosted (Local, Web)
• Contact email for the External Client App

Non-Interactive Setup

# DX Server + Claude Desktop (recommended)
sf mcp setup --target-org myOrg --mcp-servers dx --configure-client claude-desktop

# DX Server + Cursor IDE
sf mcp setup --target-org myOrg --mcp-servers dx --configure-client cursor

# DX Server only (generates .mcp.json, manual client config)
sf mcp setup --target-org myOrg --mcp-servers dx

# Hosted CRM (generates External Client App metadata)
sf mcp setup --target-org myOrg \
  --mcp-servers hosted \
  --contact-email [email protected]

# Both DX and Hosted
sf mcp setup --target-org myOrg \
  --mcp-servers both \
  --contact-email [email protected]

Options

| Flag | Description | Options | |------|-------------|---------| | --target-org, -o | Target Salesforce org (required) | Org alias or username | | --mcp-servers, -s | MCP servers to enable | dx, hosted, both | | --configure-client | Auto-configure MCP client | claude-desktop, cursor | | --workspace-dir, -w | Salesforce project directory | Path or default | | --auth-flow, -a | OAuth authentication flow | jwt, web, client_credentials | | --contact-email, -e | Contact email for app | Email address | | --output | Output directory | Default: force-app/main/default | | --config-output | .mcp.json location | local (project), global (~/) | | --deploy, -d | Deploy metadata after generation | Flag | | --json | Output results as JSON | Flag |

Multi-Org Support

Each Salesforce org gets its own uniquely named MCP server entry, allowing you to configure multiple orgs without conflicts:

{
  "mcpServers": {
    "[email protected]": {
      "command": "/path/to/npx",
      "args": ["-y", "@salesforce/mcp", "--orgs", "[email protected]", "--toolsets", "all"]
    },
    "[email protected]": {
      "command": "/path/to/npx",
      "args": ["-y", "@salesforce/mcp", "--orgs", "[email protected]", "--toolsets", "all"]
    }
  }
}

Simply run sf mcp setup for each org you want to connect.

Workspace Directory

The MCP server needs a Salesforce project directory to work with metadata operations. You have three options:

1. Use default workspace (recommended for quick setup)

sf mcp setup --target-org myOrg --configure-client claude-desktop --workspace-dir default

Creates ~/salesforce-mcp-workspace/ with a minimal sfdx-project.json.

2. Use existing project

sf mcp setup --target-org myOrg --configure-client claude-desktop --workspace-dir ~/projects/my-sf-project

Must contain a valid sfdx-project.json.

3. Interactive prompt

If you don't specify --workspace-dir, the plugin will ask you during setup.

What Gets Configured

Claude Desktop (--configure-client claude-desktop)

The plugin automatically:

• Detects your NVM installation and Node.js version
• Finds the SF CLI path
• Creates/validates the workspace directory
• Generates config with cwd pointing to the workspace
• Sets up proper PATH environment for the MCP server

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Example generated config:

{
  "mcpServers": {
    "[email protected]": {
      "command": "/Users/you/.nvm/versions/node/v22.14.0/bin/npx",
      "args": ["-y", "@salesforce/mcp", "--orgs", "[email protected]", "--toolsets", "all"],
      "cwd": "/Users/you/salesforce-mcp-workspace",
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.14.0/bin:/Users/you/.local/bin:/usr/local/bin:/usr/bin:/bin",
        "HOME": "/Users/you"
      }
    }
  }
}

After Setup

Test your connection

1. Restart Claude Desktop (Cmd+Q, then reopen)
2. Look for the hammer icon in the chat input
3. Test with: "Query the first 5 Account names from my Salesforce org"

Hosted MCP (Beta)

For Salesforce Hosted MCP Servers, the plugin generates External Client App metadata.

Generated Files (Hosted CRM)

force-app/main/default/
├── externalClientApps/
│   └── SalesforceMCP.eca-meta.xml
├── extlClntAppGlobalOauthSets/
│   └── SalesforceMCPGlobalOAuth.ecaGlblOauth-meta.xml
├── extlClntAppOauthSettings/
│   └── SalesforceMCPOAuthSettings.ecaOauth-meta.xml
└── permissionsets/
    ├── MCP_API_Access.permissionset-meta.xml
    ├── MCP_Admin.permissionset-meta.xml
    └── MCP_Hosted_Access.permissionset-meta.xml

Post-Deployment Steps

1. Deploy: sf project deploy start --source-dir force-app/main/default
2. Go to Setup > External Client App Manager
3. Find Salesforce MCP and click Manage
4. Note the Consumer Key for your MCP client configuration
5. Assign users to the MCP_Hosted_Access permission set

Troubleshooting

"Cannot connect to Salesforce CLI"

This usually means the PATH is not set correctly. Use --configure-client claude-desktop to auto-detect paths.

MCP server not showing in Claude Desktop

1. Check the config exists: cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Fully quit Claude Desktop (Cmd+Q)
3. Reopen Claude Desktop
4. Check logs: tail -f ~/Library/Logs/Claude/mcp*.log

"Cloud container" error in Claude Desktop

This is a Claude Desktop misunderstanding. MCP servers run locally on your machine, not in the cloud. The error usually means the PATH is incorrect - use --configure-client claude-desktop to fix.

Development

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
sf plugins link .

# Run tests
npm test

Version History

v0.3.3

• Added --workspace-dir flag for configuring MCP working directory
• Interactive prompt for workspace selection
• Cross-platform support (macOS Intel/ARM, Windows)
• cwd parameter in generated configs for reliable metadata operations

v0.3.2

• Published on NPM as @brightfox/sf-mcp-setup
• Org-specific MCP server naming (salesforce-{orgAlias})
• Multi-org support without config conflicts

v0.3.1

• Added --configure-client flag for auto-configuring Claude Desktop and Cursor
• Auto-detects NVM paths for reliable MCP server execution

v0.3.0

• External Client Apps for Hosted MCP (Salesforce best practice)
• 3-file ECA structure (header, global OAuth, scopes)
• PKCE required for all External Client Apps

License

MIT

Author

Brightfox