simple-salesforce-mcp

Un servidor MCP de Salesforce ligero. Habla directamente con la API REST de Salesforce a través de stdio con dos dependencias de ejecución (mcp, httpx) — creado como un reemplazo de arranque en frío rápido para el servidor DX oficial @salesforce/mcp, cuyo árbol de dependencias es demasiado pesado para entornos de sandbox.

Herramientas

Toda herramienta lleva anotaciones MCP (readOnlyHint / destructiveHint / idempotentHint). update_record y delete_record rechazan actuar a menos que la llamada incluya confirm: true, y el mensaje de rechazo indica al modelo que presente el cambio exacto al usuario y obtenga su aprobación primero. El SOQL en sí no puede modificar datos, por lo que la vía de escape sigue siendo de solo lectura.

Related MCP server: Salesforce MCP Server

Autenticación

El servidor no realiza ningún flujo OAuth por sí mismo; consume un token de acceso existente, resuelto en cada llamada de herramienta (de modo que un proceso externo puede rotar el token en cualquier momento):

1. Almacén de autenticación de Salesforce CLI en $HOME:

   • ~/.sf/config.json → {"target-org": "<username>"} (o el antiguo ~/.sfdx/sfdx-config.json → {"defaultusername": ...})

   • ~/.sfdx/<username>.json → {"accessToken": "...", "instanceUrl": "https://..."}

   Esta es la forma que escribe sf org login, y la forma que la plataforma JustParent materializa en los sandboxes (con la plataforma renovando el token de acceso antes de cada llamada). Los tokens de actualización y los secretos de cliente de estos archivos se ignoran — nunca se leen en memoria, no se almacenan ni se registran.

2. Variables de entorno (alternativa para el uso local o independiente): SALESFORCE_ACCESS_TOKEN y SALESFORCE_INSTANCE_URL.

Cuando un token es rechazado (HTTP 401 / INVALID_SESSION_ID), el servidor vuelve a leer el almacén de autenticación una vez y reintenta, y luego informa de que la conexión debe volver a establecerse.

La versión de la API REST por defecto es 62.0; se puede anular con SALESFORCE_API_VERSION.

Ejecución

# Standalone with env vars (get a token via: sf org display --json)
SALESFORCE_ACCESS_TOKEN=... \
SALESFORCE_INSTANCE_URL=https://yourorg.my.salesforce.com \
uvx --from git+https://github.com/JustParent/simple-salesforce-mcp simple-salesforce-mcp

Claude Desktop / configuración de cliente MCP genérico:

{
  "mcpServers": {
    "salesforce": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JustParent/simple-salesforce-mcp", "simple-salesforce-mcp"],
      "env": {
        "SALESFORCE_ACCESS_TOKEN": "...",
        "SALESFORCE_INSTANCE_URL": "https://yourorg.my.salesforce.com"
      }
    }
  }
}

Prueba de humo (sin red, acciones); imprime la versión, el estado de las credenciales y las herramientas; termina con el código 0):

uvx --from . simple-salesforce-mcp --test

Desarrollo

uv run pytest                    # unit tests, no network needed
uv run ruff check .              # lint
uv run ruff format .             # format (--check to verify only)
uv run mypy                      # type check (src and tests)
uv run simple-salesforce-mcp --test
npx @modelcontextprotocol/inspector uv run simple-salesforce-mcp   # interactive

La CI (.github/workflows/tests.yml) se ejecuta en cada push y pull request: la tanda de pruebas en Python 3.10–3.13, las comprobaciones de lint y formato de ruff además de mypy, y un trabajo de empaquetado que instala el paquete de la misma forma que los sandboxes (uvx --from .) para detectarse cualquier problema de empaquetado.

Notas de seguridad

• Autenticación solo con token: el servidor nunca solicita, lee ni conserva tokens de actualización.

• Las operaciones destructivas (actualizar/eliminar) están restringidas por un argumento explícito confirm=true, con instrucciones dirigidas al modelo para obtener antes la aprobación del usuario.

• Los cursores de paginación SOQL (next_url) se validan para que sean rutas /services/data/..., y los identificadores de objeto o registro se validan antes de colocarlos en las URLs.

• Las respuestas tienen un límite de tamaño con avisos de truncamiento explícitos.