salesforce-metadata-mcp

The only Salesforce MCP server that builds Agentforce agents, OmniStudio components, and DevOps Center pipelines — alongside a complete daily developer loop (schema describe, Apex read, debug logs) and 228 tools total for building, configuring, and automating Salesforce orgs directly from Claude or any MCP client.

Quick Start

npx -y salesforce-metadata-mcp

Or install globally:

npm install -g salesforce-metadata-mcp
salesforce-metadata-mcp

Configuration (Claude Desktop / Claude Code)

Add to your MCP configuration (claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": ["salesforce-metadata-mcp"],
      "env": {
        "SF_INSTANCE_URL": "https://your-org.salesforce.com",
        "SF_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

See SETUP.md for all authentication methods and detailed setup instructions.

One-click install (Claude Desktop)

Download salesforce-metadata-mcp-<version>.mcpb from the latest release, then drag it into Claude Desktop → Settings → Extensions. It prompts for your org URL and credentials — no JSON editing.

The bundle resolves the server from npm at launch rather than embedding a copy, so it always runs the current published version and never needs re-downloading after an upgrade.

Docker

docker build -t salesforce-metadata-mcp .
docker run -i --rm \
  -e SF_INSTANCE_URL="https://your-org.my.salesforce.com" \
  -e SF_ACCESS_TOKEN="your_access_token" \
  salesforce-metadata-mcp

The image builds from source, runs as a non-root user, and ships production dependencies only. Because this server speaks MCP over stdio, -i is required — the container is driven by its client, not run as a background service. SF_ALIAS will not work in a container: the Salesforce CLI's login flow needs a browser, so use token, JWT, refresh-token, or client-credentials variables instead.

Toolsets — loading 228 tools without burning your context

All 228 tools are always available. Most are not loaded into the model's context until something asks for them.

Listing every tool up front costs roughly 98,000 tokens — about half a 200k context window, spent before you type anything, whether or not the session ever touches OmniStudio or DevOps Center. A 228-candidate tool list also makes the model measurably worse at picking the right tool. So the server starts with a small core loaded and pulls in the rest on demand:

The default covers what nearly every session needs: describe/list objects, SOQL query, deploy/retrieve/delete metadata, deploy status, and core schema creation (objects, fields, formula fields, picklist values, validation rules, approval processes).

Five tools are always present and make everything else reachable:

• sf_find_tool — search all 228 tools by name and load whatever contains the matches, in one call. Ask for "create an omniscript" and it finds the tools, loads omnistudio, and they are callable immediately. This is usually all you or the model needs.
• sf_load_toolset — load named toolsets explicitly.
• sf_list_toolsets — browse all toolsets, their tool counts, and what is loaded.
• sf_call_tool — invoke any tool by name, loaded or not, without it having to appear in the tool list first. Arguments are validated and the production guard applies exactly as on a direct call.
• sf_tool_schema — return any tool's input schema, so sf_call_tool can be constructed for a tool the client cannot see.

In practice you don't manage this by hand: ask for what you want, and the model loads what it needs.

If loaded tools don't show up

Loading a toolset enables it on the server and emits notifications/tools/list_changed. A client is supposed to re-fetch tools/list when it sees that. Some clients don't — and when that happens, the load reports success, the tools really are enabled, and the model still cannot call any of them because they never entered its tool list.

Two things handle this, so no client can lose access to a tool:

• sf_load_toolset checks whether the client re-fetched and says so in its response, instead of reporting an unqualified success for tools that have become unreachable.
• sf_call_tool reaches every tool without needing a re-fetch at all. Combined with sf_tool_schema, the full 228-tool surface is usable from the handshake tool list alone — even under SF_TOOLSETS=none.

To restore the previous behaviour of loading everything at startup, set SF_TOOLSETS=all. To start with only the five meta-tools, set SF_TOOLSETS=none. To pick your own core, pass a list:

{ "env": { "SF_TOOLSETS": "metadata,objects,automation,security" } }

Available toolsets: core, metadata, objects, data, flows, automation, security, apex, lwc, ui, pages, actions, agentforce, omnistudio, omnichannel, devops, deployment, integrations, identity, reports, experience, admin, monitoring, audit, einstein, knowledge, cpq, sandbox, streaming, visualforce, aura, comms, mcp, i18n.

Flow tools live in their own flows toolset because sf_create_flow carries the full Flow element schema — 15,266 bytes (~4,126 tokens) on its own, the largest tool definition in the server. Keeping it out of the default means sessions that never build a Flow never pay for it, while sessions that do still get the complete validated schema.

Tools — 228 total

Highlights below; see TOOLS.md for the complete reference with parameters and example prompts.

Objects & Fields

Automation

Security & Access

UI & Experience

Apex Development

LWC Development

Experience Cloud

Agentforce

External Integrations

Change Sets & Deployment

MCP Server Management

Example Prompts

Build a complete object:

"Create a custom object called Project__c with fields: Name (text), Status__c (picklist: Planning/Active/Complete), Budget__c (currency), then add a validation rule requiring Budget when Status is Active."

Deploy Apex:

"Create an Apex class called OpportunityService that queries all Opps with Amount > 100000. Then create a test class for it."

Create a flow:

"Create a record-triggered flow on Opportunity that fires after save when Stage = Closed Won. Send an email alert to the owner and create a follow-up Task due in 30 days."

Set up an LWC:

"Create a Lightning Web Component called accountSummary that displays account name, industry, and annual revenue. Make it available on Record Pages."

Agentforce setup:

"Create an Agentforce agent called SalesAssistant. Then create a GetOrders action linked to the Get_Account_Orders flow. Then create an OrderManagement topic with actions: [GetOrders]. Finally wire SalesAssistant to topic OrderManagement."

Environment Variables

Production write guard

This server hands an LLM a Salesforce credential, and the LLM decides what to do with it. Any text the model reads on the way — a case comment, a field description, a retrieved .flow file, an email body — can carry an instruction, and nothing downstream can tell it apart from one you typed.

So against a production org, nine tools are refused by default:

Metadata creation is not affected. All 137 sf_create_* tools, sf_deploy_metadata and sf_retrieve_metadata work against production exactly as before — authoring metadata by natural language is the point of this package, and a guard that taxed it would just get switched off.

Apex authoring (sf_create_apex_class, sf_create_apex_trigger) is also not blocked, even though a trigger runs on every DML. The line drawn is auditability: created Apex is metadata — it has a name, an author and a deploy record, and can be found and removed. sf_execute_anonymous_apex leaves nothing to find, which is why that one is blocked.

An org counts as production only when it is not a sandbox, not a Developer Edition org, and not on a trial/scratch expiry. Sandboxes, dev orgs and scratch orgs are never gated.

{ "env": { "SF_PRODUCTION_GUARD": "strict" } }   // refuse ALL writes on production
{ "env": { "SF_PRODUCTION_GUARD": "off" } }      // no guard at all

The guard is a hard refusal, not a confirmation prompt: a prompt the calling agent can approve by itself is not a control, and this server is often run with client permissions bypassed. Only the environment variable lifts it.

Documentation

• SETUP.md — Prerequisites, authentication, Claude configuration
• TOOLS.md — All 228 tools with full parameter documentation
• AGENTFORCE.md — Agentforce agent creation guide
• APEX_LWC.md — Apex and LWC development guide
• CHANGELOG.md — Version history

Bugs & Feature Requests

Found a bug or want a new tool? Open an issue — there are templates for bug reports and feature requests. Please include the package version and the tool name, and remove any org URLs or credentials before posting.

License

MIT