sf-query

Natural-language SOQL query over a Salesforce org via the Salesforce DX MCP server (brew formula salesforce-mcp / npm @salesforce/mcp, binary sf-mcp-server, Apache-2.0, GA 2026). The user asks a business question in prose; this skill composes a SOQL string, calls the upstream run_soql_query MCP tool, and renders the JSON rows back as a table or a narrative answer.

Read-only. The .mcp.json ships only the data toolset, which exposes a single tool: run_soql_query. No DML, no INSERT / UPDATE / DELETE, no metadata mutation — those tools are structurally absent from the MCP surface in v0.1.0.

SOQL only — no SOSL. Upstream salesforcecli/mcp v0.30.9 data toolset exposes no SOSL tool. If the user asks for full-text search ("find anything about acme corp"), pick a likely target object (Account / Contact / Case) and use a SOQL WHERE Name LIKE '%acme corp%' (or similar) pattern; tell the user this is a SOQL approximation and SOSL is deferred to Phase 2+.

Prerequisites

One-time setup:

1. Run /salesforce-toolkit:sf-setup and complete the browser OAuth flow. This installs sf CLI + salesforce-mcp via brew and authenticates the default org.
2. Verify the MCP server is alive: in Claude Code, run /mcp and confirm salesforce is listed as connected (this is the MCP server name from .mcp.json; the underlying binary is sf-mcp-server, shipped by brew formula salesforce-mcp). If it shows disconnected or error, run bash "${CLAUDE_PLUGIN_ROOT}/scripts/sf/refresh-auth.sh" to re-auth the OAuth token, then restart the MCP server.
3. Confirm the default org responds: sf org display --json should return a JSON blob with instanceUrl and a non-expired accessTokenExpirationDate.

If any of the three checks fail, stop and tell the user to run /salesforce-toolkit:sf-setup (or --force-reauth if the token expired). Do not try to compose queries against a dead MCP server — the error messages will be cryptic.

Workflow