Salesforce TypeScript Connector

Interaja com dados do Salesforce usando consultas SOQL, buscas SOSL e operações CRUD por meio de um servidor MCP TypeScript.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Conector MCP Salesforce TypeScript

Uma implementação em TypeScript de um servidor Model Context Protocol (MCP) para integração com Salesforce, permitindo que LLMs interajam com dados do Salesforce por meio de consultas SOQL, pesquisas SOSL e operações CRUD.

Recursos

  • 🔐 Autenticação Simplificada por Senha: Fluxo Seguro de Credenciais de Senha do Proprietário do Recurso OAuth 2.0
  • 📊 SOQL e SOSL: Execute consultas e pesquisas no Salesforce
  • 🔍 Acesso a Metadados: Recupere campos, rótulos e tipos de objetos
  • ✏️ Operações CRUD: Crie, leia, atualize e exclua registros
  • 🛠️ API de Ferramentas: Execute solicitações da API de Ferramentas
  • ⚡ Apex REST: Execute solicitações Apex REST
  • 🌐 API REST: Faça chamadas diretas à API REST do Salesforce
  • 🐳 Pronto para Docker: Sem valores fixos, totalmente configurável por variáveis de ambiente
  • 🔄 Atualização de Token: Atualização automática de token para sessões de longa duração

Ferramentas Disponíveis

  • authenticate_password - Autentique usando nome de usuário/senha com OAuth
  • run_soql_query - Execute consultas SOQL
  • run_sosl_search - Execute pesquisas SOSL
  • get_object_fields - Obtenha metadados para objetos do Salesforce
  • get_record - Recupere registros específicos por ID
  • create_record - Crie novos registros
  • update_record - Atualize registros existentes
  • delete_record - Exclua registros
  • tooling_execute - Execute solicitações da API de Ferramentas
  • apex_execute - Execute solicitações Apex REST
  • restful - Faça chamadas diretas à API REST

Início Rápido com Docker

Pré-requisitos

  1. Crie um Connected App no Salesforce:

    • Vá para Configuração → Aplicativos → Gerenciador de Aplicativos → Novo Connected App
    • Preencha as informações básicas (Nome do Aplicativo, Nome da API, E-mail de Contato)
    • Habilite as Configurações de OAuth
    • Defina a URL de retorno: http://localhost:8080/callback (obrigatória, mas não utilizada)
    • Selecione os Escopos de OAuth:
      • Acesse suas informações básicas (id, perfil, e-mail, endereço, telefone)
      • Execute solicitações em seu nome a qualquer momento (refresh_token, offline_access)
      • Acesse e gerencie seus dados (api)
    • Salve e anote a Consumer Key e o Consumer Secret

  2. Obtenha seu Security Token:

    • Vá para Configuração → Minhas Informações Pessoais → Redefinir Security Token
    • Verifique seu e-mail para obter o novo security token

Usando a Imagem Docker

Baixe e execute a imagem Docker mais recente:

# Pull the image
docker pull steffensbola/salesforce-mcp-ts:latest

# Run with your credentials
docker run -p 3000:3000 \
  -e SALESFORCE_CLIENT_ID=your_consumer_key \
  -e SALESFORCE_CLIENT_SECRET=your_consumer_secret \
  -e SALESFORCE_USERNAME=your_username@domain.com \
  -e SALESFORCE_PASSWORD=your_password \
  -e SALESFORCE_SECURITY_TOKEN=your_security_token \
  -e SALESFORCE_SANDBOX=true \
  steffensbola/salesforce-mcp-ts:latest

Configuração do MCP

VS Code usando imagem Docker

Adicione ao seu .vscode/mcp.json:

{
  "servers": {
    "salesforce": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "SALESFORCE_CLIENT_ID=your_consumer_key",
        "-e", "SALESFORCE_CLIENT_SECRET=your_consumer_secret",
        "-e", "SALESFORCE_USERNAME=your_username@domain.com",
        "-e", "SALESFORCE_PASSWORD=your_password",
        "-e", "SALESFORCE_SECURITY_TOKEN=your_token",
        "-e", "SALESFORCE_SANDBOX=true",
        "steffensbola/salesforce-mcp-ts:latest"
      ]
    }
  }
}

Você também pode usar volumes para montar um arquivo de configuração em vez de passar variáveis de ambiente:

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

Claude Desktop usando imagem Docker

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "SALESFORCE_CLIENT_ID=your_consumer_key",
        "-e", "SALESFORCE_CLIENT_SECRET=your_consumer_secret",
        "-e", "SALESFORCE_USERNAME=your_username@domain.com",
        "-e", "SALESFORCE_PASSWORD=your_password",
        "-e", "SALESFORCE_SECURITY_TOKEN=your_token",
        "-e", "SALESFORCE_SANDBOX=true",
        "steffensbola/salesforce-mcp-ts:latest"
      ]
    }
  }
}

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

Obrigatórias (Autenticação OAuth)

  • SALESFORCE_CLIENT_ID - Consumer Key do seu Connected App
  • SALESFORCE_CLIENT_SECRET - Consumer Secret do seu Connected App
  • SALESFORCE_USERNAME - Seu nome de usuário do Salesforce
  • SALESFORCE_PASSWORD - Sua senha do Salesforce
  • SALESFORCE_SECURITY_TOKEN - Seu security token do Salesforce

Opcionais

  • SALESFORCE_SANDBOX - Defina como "true" para sandbox, "false" para produção (padrão: "false")

Alternativa (Autenticação Direta por Token)

Em vez de nome de usuário/senha, você pode usar:

  • SALESFORCE_ACCESS_TOKEN - Token de acesso direto
  • SALESFORCE_INSTANCE_URL - URL da instância do Salesforce (ex.: https://your-instance.my.salesforce.com)

Compatibilidade Retroativa

O servidor também suporta nomes alternativos de variáveis:

  • SF_CONSUMER_KEY / SF_CONSUMER_SECRET
  • SF_USERNAME / SF_PASSWORD / SF_SECURITY_TOKEN

Usando Docker Compose

  1. Crie um arquivo .env com suas variáveis de ambiente:
SALESFORCE_CLIENT_ID=your_consumer_key
SALESFORCE_CLIENT_SECRET=your_consumer_secret
SALESFORCE_USERNAME=your_username@domain.com
SALESFORCE_PASSWORD=your_password
SALESFORCE_SECURITY_TOKEN=your_token
SALESFORCE_SANDBOX=true
DOCKER_HUB_USERNAME=steffensbola
  1. Execute usando Docker Compose:
docker-compose up -d

Exemplos

Usando as Ferramentas

Após conectar, você pode usar as ferramentas por meio do seu cliente MCP:

Autenticação:

Please authenticate with Salesforce using my credentials

Consultar Dados:

Run this SOQL query: SELECT Id, Name, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10

Pesquisar:

Search for contacts named "John" using SOSL

Obter Metadados:

Get all the fields for the Contact object

Criar Registro:

Create a new Account with Name "Test Company" and Industry "Technology"

Solução de Problemas

Problemas Comuns

  1. Falha na Autenticação

    • Verifique se as credenciais estão corretas
    • Confirme se os escopos de OAuth do Connected App incluem "Acessar e gerenciar seus dados (api)"
    • Garanta que o security token esteja atualizado (redefina se necessário)
    • Verifique se a configuração de sandbox corresponde ao tipo da sua organização

  2. O Contêiner Não Inicia

    • Garanta que CLIENT_ID e CLIENT_SECRET sejam fornecidos
    • Verifique se todas as variáveis de ambiente obrigatórias estão definidas
    • Confirme se o Docker tem acesso para baixar a imagem

  3. Erros de Rede

    • Verifique a conexão com a internet
    • Verifique o status do serviço do Salesforce
    • Confirme se as configurações do firewall permitem conexões HTTPS de saída

Modo de Depuração

Para registro detalhado, adicione a variável de ambiente de depuração:

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

Contribuindo

Consulte CONTRIBUTING.md para informações sobre:

  • Arquitetura do projeto e configuração de desenvolvimento
  • Execução a partir do código-fonte
  • Diretrizes de contribuição e processo de pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Links