Claude Code Salesforce MCP Setup: Installation and Configuration Guide (2026)

This guide covers the complete Claude Code Salesforce MCP setup — from installing the CLI to running your first SOQL query. The Salesforce MCP server gives you natural language access to your entire org: SOQL queries, bulk record updates, metadata deployment, Apex tests, and more. Setup takes under 30 minutes.

Most tutorials jump straight to the .mcp.json file and skip the parts that cause 80% of failures: Node version mismatches, org authorization edge cases, token expiry, and Windows PATH issues. This guide covers all of them, step by step.

It also covers connected app creation for teams using the Hosted MCP server, token management patterns for shared environments, and five starter SOQL queries you can paste straight into Claude Code to confirm everything is working.

What Is the Salesforce MCP Setup?

The Claude Code Salesforce MCP setup is the process of connecting Claude Code to a live Salesforce org using Model Context Protocol — Anthropic's open standard for giving AI models access to external tools and data sources.

Salesforce published its own MCP implementation as @salesforce/mcp — an open-source npm package maintained by the Salesforce CLI team. Once configured, Claude Code can interact with your org using natural language: query records, deploy metadata, run tests, and manage users.

The setup has three components: authenticating your Salesforce org with the CLI, configuring Claude Code via .mcp.json, and optionally creating a Connected App for teams using the cloud-hosted OAuth server. This guide covers all three.

According to Salesforce's April 2026 developer announcement, every Developer Edition org now includes access to Salesforce-Hosted MCP Servers at no additional cost. The @salesforce/mcp package exposes 60+ tools across 15 toolsets — covering data operations, metadata, users, Apex testing, code analysis, and DevOps Center pipelines.

Prerequisites

Confirm you have the following before starting. Missing any one of these is the cause of most setup failures.

Step 1: Install Salesforce CLI and Node.js

If you already have Node.js 18+ and the unified Salesforce CLI installed, skip this step and go to Step 2.

Install or upgrade Node.js

# Check current Node version
node --version

# Using nvm (recommended — lets you switch versions per project)
nvm install 20
nvm use 20
nvm alias default 20

# Verify
node --version  # Should show v20.x.x

Install the Salesforce CLI

# Install the unified SF CLI
npm install -g @salesforce/cli

# Verify installation
sf --version

# Expected output (version numbers will vary):
# @salesforce/cli/2.x.x ...

Verify the MCP package is accessible

Test that npx can resolve the @salesforce/mcp package before configuring Claude Code. This catches network or proxy issues early.

npx -y @salesforce/mcp --help

# Expected output includes flags:
# --orgs        Comma-separated list of org aliases
# --toolsets    Comma-separated list of toolsets to enable
# --tools       Specific tools to load
# --dynamic-tools  Load tools on-demand
# --debug       Enable debug logging

If this command returns an error, confirm that your npm registry is accessible and that Node.js 18+ is active. On corporate networks with proxy settings, you may need to configure npm config set proxy before proceeding.

Step 2: Create a Connected App (Optional for DX)

For the DX MCP server (local npx), you do not need to create a Connected App. The Salesforce CLI ships with its own registered connected app, and sf org login web uses it automatically. Skip to Step 3.

You need a custom Connected App only if you are configuring the Hosted MCP server for team-wide access, or if your org's admin has restricted the default CLI app.

Create a Connected App in Salesforce Setup

1. Go to Setup → search for App Manager → click New Connected App
2. Set a name (e.g., Claude Code MCP) and enter your email as the contact
3. Check Enable OAuth Settings
4. Set Callback URL to http://localhost:1717/OauthRedirect (standard Salesforce CLI callback)
5. Add OAuth scopes: api, refresh_token, offline_access. For Hosted MCP, also add sfap_api
6. Save. Salesforce will take 2–10 minutes to activate the app after creation

After the app activates, copy the Consumer Key (Client ID) and Consumer Secret. Store them securely — you'll need them when running sf org login web --client-id <consumer-key> to authorize with your custom app.

# Authorize using your custom Connected App
sf org login web   --client-id YOUR_CONSUMER_KEY   --alias my-org-custom-app

# Confirm
sf org list

Step 3: Authorize Your Salesforce Org

The Salesforce MCP server uses credentials stored by the Salesforce CLI — it does not handle authentication itself. This keeps secrets off disk and out of your config files.

Authorize production or developer org

# Standard web-based OAuth login
sf org login web --alias my-prod-org

# Confirms authorization and opens a browser for Salesforce login
# After login, the token is stored in your system credential store

Authorize a sandbox

# Sandbox requires the test.salesforce.com instance URL
sf org login web   --instance-url https://test.salesforce.com   --alias my-sandbox

# List all authorized orgs
sf org list

Set a default org for a project

Setting a project-level default means you can use DEFAULT_TARGET_ORG in your MCP config. Each developer sets their own local default — safe for shared repos.

# Set a default for this directory only (not global)
sf config set target-org my-sandbox --global false

# Verify
sf config get target-org

# Output shows:
# key         value
# ──────────  ─────────────
# target-org  my-sandbox

Authorize without a browser (JWT flow)

For CI/CD environments where interactive browser login is not possible, use the JWT bearer flow. This requires a private key and a Connected App configured with a certificate.

# JWT-based authorization for CI/CD
sf org login jwt   --username ci-user@myorg.com   --jwt-key-file server.key   --client-id YOUR_CONSUMER_KEY   --alias ci-org

For most individual developers and RevOps teams, sf org login web is sufficient. JWT flow is for automated pipelines only.

Step 4: Configure .mcp.json for Claude Code

The .mcp.json file is Claude Code's address book for MCP servers. Place it in your project root. Claude reads it on startup and launches the configured servers automatically.

Minimal configuration

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs",
        "DEFAULT_TARGET_ORG"
      ]
    }
  }
}

DEFAULT_TARGET_ORG is resolved at runtime from whichever org you set with sf config set target-org.

With toolsets and dynamic loading (recommended)

The full MCP server exposes 60+ tools. Loading all of them at once consumes Claude's context window. Use --toolsets to limit scope, and --dynamic-tools to load tools on-demand.

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs",
        "my-sandbox",
        "--toolsets",
        "data,metadata,users",
        "--dynamic-tools"
      ]
    }
  }
}

For GTM and RevOps use cases, data,metadata,users covers everything you need: SOQL queries, record operations, field creation, and user management. Avoid enabling testing or devops-center unless your workflow specifically requires them.

Available toolsets reference

Multi-org configuration

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs",
        "my-sandbox,my-prod-org",
        "--toolsets",
        "data,metadata",
        "--dynamic-tools"
      ]
    }
  }
}

With multiple orgs, Claude can compare records between sandbox and production, or verify that a metadata deployment matches what is live. Separate aliases with commas — no spaces.

Step 5: Token Management and Session Refresh

Salesforce OAuth tokens expire. The MCP server does not handle token refresh on its own — it relies on the CLI's credential store. When a session expires, Claude will return an authentication error on the next MCP call.

Refresh an expired token

# Re-authorize the specific org that expired
sf org login web --alias my-sandbox

# Check org status after refresh
sf org display --target-org my-sandbox

After re-authorizing, restart Claude Code from your project directory. The MCP server picks up the refreshed credentials automatically on next launch.

Extend session timeout in Salesforce Setup

If sessions expire more frequently than expected, check the session timeout setting in Salesforce. Go to Setup → Security → Session Settings and increase the Timeout Value to 8 or 24 hours.

For developer orgs and sandboxes, a longer timeout reduces friction during active development. For production orgs connected to sensitive data, maintain a shorter timeout and re-authorize before each work session.

Token storage location

The Salesforce CLI stores OAuth tokens in your operating system credential store — not in any file Claude Code can read. On macOS: Keychain. On Windows: Windows Credential Manager. On Linux: the ~/.config/@salesforce directory (encrypted).

Never store Salesforce credentials in .mcp.json, CLAUDE.md, or environment variables. The CLI credential store is the secure pattern — use it.

# Display org details including token expiry
sf org display --target-org my-sandbox --json

# Output includes:
# "expirationDate": "2026-05-26T10:00:00.000Z"
# "connectedStatus": "Connected"

Step 6: Test Your First Queries

Start Claude Code from the directory containing your .mcp.json file. Claude reads the config on launch and connects to the MCP server automatically.

# Launch Claude Code from your project root
claude

Use these five starter prompts to confirm end-to-end connectivity. Each tests a different part of the MCP setup.

Test 1: Verify org connection

A successful response shows your authorized orgs. This confirms the CLI connection works before you run any data queries.

Test 2: Run a basic SOQL query

Test 3: Query account data

Test 4: Check org limits

Test 5: List custom fields on Opportunity

If all five prompts return structured data, your claude code salesforce mcp setup is complete and working. If any return errors, jump to the troubleshooting section below.

For more complex automation workflows using Claude Code with Salesforce, see our guide on Claude Code Salesforce MCP workflows and how GTM teams use Claude Code for revenue operations.

Advanced Configuration Options

Hosted MCP server via mcp-remote (Beta)

The Hosted MCP server lets teams share Salesforce access without per-machine CLI setup. It requires the mcp-remote package as an OAuth proxy.

{
  "mcpServers": {
    "salesforce-hosted": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.salesforce.com/sse"
      ]
    }
  }
}

On first connection, a browser opens for OAuth. Approve scopes api, refresh_token, and sfap_api. The DX server remains more stable for individual developers — prefer the Hosted server once it reaches GA.

Debug logging

Add the --debug flag to your MCP args to log all server activity. Copy the output when filing issues on the salesforcecli/mcp GitHub repository.

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--toolsets",
        "data,metadata",
        "--dynamic-tools",
        "--debug"
      ]
    }
  }
}

Scoping specific tools (not toolsets)

If you want even finer control, use --tools instead of --toolsets to load only specific named tools. Run npx -y @salesforce/mcp --help to see the full list of available tool names.

Windows-Specific Setup Notes

The Salesforce MCP setup works on Windows, but two issues come up consistently: PATH configuration and shell compatibility.

Issue 1: 'sf' not recognized after install

After running npm install -g @salesforce/cli on Windows, the sf command may not be recognized in PowerShell or Command Prompt. Fix: close all terminal windows, then open a new one. If the issue persists, add the npm global bin directory to your PATH manually.

# Find npm global bin directory
npm config get prefix

# Add <prefix>in to Windows PATH via System Properties
# > Environment Variables > Path > New > paste the path

Issue 2: npx path resolution in .mcp.json

On Windows, Claude Code may fail to resolve npx if it is not in the system PATH. Use the absolute path to npx in your .mcp.json as a fallback.

{
  "mcpServers": {
    "salesforce": {
      "command": "C:\\Users\\YourName\\AppData\\Roaming\\npm\\npx.cmd",
      "args": [
        "-y",
        "@salesforce/mcp",
        "--orgs",
        "DEFAULT_TARGET_ORG",
        "--toolsets",
        "data,metadata"
      ]
    }
  }
}

Find your npx path by running where npx in PowerShell. Replace backslashes with double backslashes in the JSON value.

Issue 3: nvm-windows vs nvm (Unix)

The nvm command on Windows uses nvm-windows (different from the Unix version). Commands are the same: nvm install 20 and nvm use 20. After switching versions, restart your terminal before running any npm commands.

Pair With SyncGTM for Enrichment Workflows

The Salesforce MCP server is a query and modification tool. It reads and writes data that already exists in your org. It does not source new data from external providers.

If your Salesforce contacts are missing emails, phone numbers, or firmographic fields — that is an enrichment problem, not an MCP problem. SyncGTM connects to Salesforce and auto-enriches every contact and account with data from 50+ providers — waterfall enrichment, ICP scoring, and direct sync. See SyncGTM pricing for plans starting at $99/mo.

A common pattern: use Claude Code with the MCP server to create custom fields (e.g., ICP_Score__c), then use SyncGTM to populate those fields with enrichment data automatically. See the sign-up enrichment workflow and the best Salesforce enrichment tools in 2026 for the full picture.

For GTM engineers building broader automation stacks, the top GTM MCPs for Claude Code lists the other MCP servers worth adding alongside the Salesforce one.