Conector TypeScript MCP Salesforce

Una implementación de TypeScript de un servidor de protocolo de contexto de modelo (MCP) para la integración de Salesforce, que permite a los LLM interactuar con los datos de Salesforce mediante consultas SOQL, búsquedas SOSL y operaciones CRUD.

Características

• autenticación de contraseña simplificada: Flujo seguro de credenciales de contraseña de propietario de recursos OAuth 2.0
• 📊SOQL y SOSL: Ejecute consultas y búsquedas en Salesforce
• 🔍 Acceso a metadatos: Recuperar campos, etiquetas y tipos de objetos
• ✏️ Operaciones CRUD: Crear, leer, actualizar y eliminar registros
• 🛠️ API de herramientas: Ejecutar solicitudes de la API de herramientas
• apex REST: Ejecutar peticiones REST de Apex
• 🌐 API REST: Realice llamadas REST API directas a Salesforce
• 🐳 Docker Ready: Sin valores codificados, totalmente configurable a través de variables de entorno
• actualización de tokens: Actualización automática de tokens para sesiones de larga duración

Herramientas disponibles

• authenticate_password - Autenticación mediante nombre de usuario/contraseña con OAuth
• run_soql_query - Ejecutar consultas SOQL
• run_sosl_search - Ejecuta búsquedas SOSL
• get_object_fields - Obtener metadatos de objetos Salesforce
• get_record - Recupera registros específicos por ID
• create_record - Crear nuevos registros
• update_record - Actualizar registros existentes
• delete_record - Eliminar registros
• tooling_execute - Ejecutar solicitudes de API de herramientas
• apex_execute - Ejecutar solicitudes REST de Apex
• restful - Hacer llamadas directas a la API REST

Inicio rápido con Docker

Requisitos previos

1. Cree una aplicación conectada en Salesforce:

   • Vaya a Configuración → Aplicaciones → App Manager → Nueva aplicación conectada
   • Rellene la información básica (nombre de la aplicación, nombre de la API, correo electrónico de contacto)
   • Habilite la configuración de OAuth
   • Establezca la URL de devolución de llamada: http://localhost:8080/callback (obligatorio pero no se utiliza)
   • Seleccione los ámbitos de OAuth
     • Acceder a su información básica (id, perfil, correo electrónico, dirección, teléfono)
     • Realizar solicitudes en tu nombre en cualquier momento (refresh_token, offline_access)
     • Acceder y gestionar tus datos (api)
   • Guardar y anotar la Clave y el Secreto del Consumidor

2. Obtén tu token de seguridad:

   • Ve a Configuración → Mi información personal → Restablecer token de seguridad
   • Revisa tu correo electrónico para recibir el nuevo token de seguridad

Uso de la imagen de Docker

Extrae y ejecuta la última imagen Docker:

# Extraiga la imagen docker pull steffensbola/salesforce-mcp-ts:latest # Ejecútela con sus credenciales docker run -p 3000:3000 \ -e SALESFORCE_CLIENT_ID=su_clave_de_consumidor \ -e SALESFORCE_CLIENT_SECRET=su_secreto_de_consumidor \ -e SALESFORCE_USERNAME=your_username@domain.com \ -e SALESFORCE_PASSWORD=su_contraseña \ -e SALESFORCE_SECURITY_TOKEN=su_token_de_seguridad \ -e SALESFORCE_SANDBOX=true \ steffensbola/salesforce-mcp-ts:latest

Configuración de MCP

VS Code utilizando una imagen Docker

Añada a su .vscode/mcp.json:

{ "servers": { "salesforce": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SALESFORCE_CLIENT_ID=su_clave_consumidor", "-e", "SALESFORCE_CLIENT_SECRET=su_secreto_consumidor", "-e", "SALESFORCE_USERNAME=your_username@domain.com",
        "-e", "SALESFORCE_PASSWORD=su_contraseña", "-e", "SALESFORCE_SECURITY_TOKEN=su_token", "-e", "SALESFORCE_SANDBOX=true", "steffensbola/salesforce-mcp-ts:latest" ] } } }

También puede utilizar volúmenes para montar un fichero de configuración en lugar de pasar variables de entorno:

{ "servers": { "salesforce": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "${workspaceFolder}/.env:/app/.env", "steffensbola/salesforce-mcp-ts:latest" ] } }

Claude Desktop utilizando una imagen Docker

Añada a su claude_desktop_config.json:

{ "mcpServers": { "salesforce": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SALESFORCE_CLIENT_ID=su_clave_consumidor", "-e", "SALESFORCE_CLIENT_SECRET=su_secreto_consumidor", "-e", "SALESFORCE_USERNAME=your_username@domain.com",
        "-e", "SALESFORCE_PASSWORD=su_contraseña", "-e", "SALESFORCE_SECURITY_TOKEN=su_token", "-e", "SALESFORCE_SANDBOX=true", "steffensbola/salesforce-mcp-ts:latest" ] } } }

Variables de entorno

El servidor requiere las siguientes variables de entorno:

Obligatorio (autenticación OAuth)

• SALESFORCE_CLIENT_ID - Clave de consumidor de su aplicación conectada
• SALESFORCE_CLIENT_SECRET - Secreto del consumidor de su aplicación conectada
• SALESFORCE_USERNAME - Su nombre de usuario de Salesforce
• SALESFORCE_PASSWORD - Su contraseña de Salesforce
• SALESFORCE_SECURITY_TOKEN - Su token de seguridad de Salesforce

Opcional

• SALESFORCE_SANDBOX - Establecer como "true" para sandbox, "false" para producción (por defecto: "false")

Alternativa (autenticación por token directa)

En lugar de nombre de usuario/contraseña, puede utilizar

• SALESFORCE_ACCESS_TOKEN - Token de acceso directo
• SALESFORCE_INSTANCE_URL - URL de instancia de Salesforce (por ejemplo, https://your-instance.my.salesforce.com)

Compatibilidad con versiones anteriores

El servidor también admite nombres de variable alternativos:

• SF_CONSUMER_KEY / SF_CONSUMER_SECRET
• SF_USERNAME / SF_PASSWORD / SF_SECURITY_TOKEN

Uso de Docker Compose

1. Cree un archivo .env con sus variables de entorno:

SALESFORCE_CLIENT_ID=su_clave_consumidor SALESFORCE_CLIENT_SECRET=su_secreto_consumidor SALESFORCE_USERNAME=your_username@domain.com SALESFORCE_PASSWORD=su_contraseña SALESFORCE_SECURITY_TOKEN=su_token SALESFORCE_SANDBOX=true DOCKER_HUB_USERNAME=steffensbola

2. Ejecutar usando Docker Compose:

docker-compose up -d

Ejemplos

Uso de las herramientas

Una vez conectado, puede utilizar las herramientas a través de su cliente MCP:

Autenticación:

Por favor, autentifíquese con Salesforce utilizando mis credenciales

Consultar datos:

Ejecute esta consulta SOQL: SELECT Id, Name, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10

Buscar:

Buscar contactos con el nombre "John" utilizando SOSL

Obtener Metadatos:

Obtener todos los campos del objeto Contacto

Crear registro:

Crear una nueva Cuenta con Nombre "Empresa de Pruebas" e Industria "Tecnología"

Resolución de problemas

Problemas comunes

1. Error de autenticación

   • Compruebe que las credenciales son correctas
   • Compruebe que los ámbitos de OAuth de la aplicación conectada incluyen "Acceder y gestionar sus datos (api)"
   • Asegúrese de que el token de seguridad está actualizado (restablézcalo si es necesario)
   • Compruebe que la configuración del entorno de pruebas coincide con su tipo de organización

2. El contenedor no se inicia

   • Asegúrese de que tanto CLIENT_ID y CLIENT_SECRET se proporcionan
   • Compruebe que todas las variables de entorno necesarias están configuradas
   • Compruebe que Docker tiene acceso para extraer la imagen

3. Errores de red

   • Compruebe la conexión a Internet
   • Compruebe el estado del servicio Salesforce
   • Compruebe que la configuración del cortafuegos permite conexiones HTTPS salientes

Modo de depuración

Para un registro detallado, añada la variable de entorno debug:

docker run -e DEBUG=true \ -e SALESFORCE_CLIENT_ID=... \ # ... otras variables steffensbola/salesforce-mcp-ts:latest

Contribución

Consulte CONTRIBUTING.md para obtener información sobre:

• Arquitectura del proyecto y configuración de desarrollo
• Ejecución desde el código fuente
• Directrices de contribución y proceso de pull request

Licencia

Licencia MIT - véase el archivo LICENSE para más detalles.

Enlaces

• Documentación de Salesforce
• Protocolo de contexto de modelo
• Repositorio Docker Hub