sapient-mcp

MCP para automatizar SAP GUI

Documentação

SAPient MCP

Automação inteligente de SAP GUI para agentes de IA

Um servidor Model Context Protocol (MCP) pronto para produção que permite que LLMs (Claude, Copilot, Cursor, etc.) automatizem o SAP GUI usando a biblioteca RoboSAPiens.

Clientes MCP compatíveis

Cliente	Modo	Observações
Claude Desktop	stdio	Suporte completo
Claude Code	stdio	Suporte completo
Cursor	stdio ou SSE	Suporte completo
VS Code (GitHub Copilot)	stdio ou SSE	Requer modo agente do Copilot
Windsurf	stdio ou SSE	Suporte completo
Qualquer cliente MCP	SSE/HTTP	Via flag `--port`

Pré-requisitos

Requisito	Detalhes
SO	Apenas Windows 10/11 (SAP GUI é exclusivo para Windows)
Python	3.10 ou mais recente
SAP GUI	SAP GUI para Windows instalado
SAP Scripting	Deve estar habilitado no servidor (RZ11: `sapgui/user_scripting=TRUE`) E nas configurações do cliente SAP Logon

Habilitar SAP GUI Scripting (configuração única)

Abra SAP Logon → Customize Local Layout (Alt+F12) → Options
Vá para Accessibility & Scripting → Scripting
✅ Habilite o scripting
❌ Desabilite "Notificar quando um script anexar a uma sessão SAP GUI em execução"
❌ Desabilite "Notificar quando um script abrir uma conexão"
Peça ao administrador BASIS para executar a transação RZ11 → defina sapgui/user_scripting = TRUE

Instalação

# Clone the repo
git clone https://github.com/yourorg/sapient-mcp.git
cd sapient-mcp

# Install (using pip or uv)
pip install -e .

# Or with uv (recommended)
uv pip install -e .

Início Rápido

Opção A — modo stdio (clientes locais)

O SAPient MCP funciona com qualquer cliente compatível com MCP. Escolha o seu abaixo.

Claude Desktop

Edite %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "sapient": {
      "command": "python",
      "args": ["-m", "sapient_mcp"],
      "env": {
        "SAPIENT_MCP_SAPLOGON_PATH": "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui\\saplogon.exe",
        "SAPIENT_MCP_CAPS": "screenshot,codegen,advanced",
        "SAPIENT_MCP_OUTPUT_DIR": "C:\\sapient_output"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add sapient python -m sapient_mcp \
  -- --caps screenshot,codegen,advanced

Ou edite ~/.claude/mcp.json / .claude/mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "sapient": {
      "command": "python",
      "args": ["-m", "sapient_mcp", "--caps", "screenshot,codegen,advanced"],
      "env": {
        "SAPIENT_MCP_SAPLOGON_PATH": "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui\\saplogon.exe",
        "SAPIENT_MCP_OUTPUT_DIR": "C:\\sapient_output"
      }
    }
  }
}

Cursor

Vá para Cursor Settings → MCP → Add new MCP Server → digite command, depois insira:

python -m sapient_mcp --caps screenshot,codegen,advanced

Ou edite ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sapient": {
      "command": "python",
      "args": ["-m", "sapient_mcp", "--caps", "screenshot,codegen,advanced"],
      "env": {
        "SAPIENT_MCP_SAPLOGON_PATH": "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui\\saplogon.exe",
        "SAPIENT_MCP_OUTPUT_DIR": "C:\\sapient_output"
      }
    }
  }
}

VS Code (GitHub Copilot)

Instale o servidor MCP via CLI do VS Code:

code --add-mcp '{"name":"sapient","command":"python","args":["-m","sapient_mcp","--caps","screenshot,codegen,advanced"]}'

Ou adicione a .vscode/mcp.json no seu workspace:

{
  "servers": {
    "sapient": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "sapient_mcp", "--caps", "screenshot,codegen,advanced"],
      "env": {
        "SAPIENT_MCP_SAPLOGON_PATH": "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui\\saplogon.exe",
        "SAPIENT_MCP_OUTPUT_DIR": "C:\\sapient_output"
      }
    }
  }
}

Windsurf

Edite ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sapient": {
      "command": "python",
      "args": ["-m", "sapient_mcp", "--caps", "screenshot,codegen,advanced"],
      "env": {
        "SAPIENT_MCP_SAPLOGON_PATH": "C:\\Program Files (x86)\\SAP\\FrontEnd\\SAPgui\\saplogon.exe",
        "SAPIENT_MCP_OUTPUT_DIR": "C:\\sapient_output"
      }
    }
  }
}

Observação: No modo stdio, o SAPient MCP nunca escreve em stdout ou stderr — todos os logs vão apenas para o arquivo de log. Isso é necessário para uma comunicação JSON-RPC limpa em todos os clientes.

Opção B — modo SSE/HTTP (remoto / CI / multi-usuário)

Melhor quando a máquina SAP está separada de onde o cliente de IA é executado, ou quando vários desenvolvedores querem compartilhar uma única instância do SAPient.

Execute o servidor na sua máquina Windows com SAP:

python -m sapient_mcp --port 8765 --caps screenshot,codegen,advanced

Depois aponte qualquer cliente MCP para o endpoint HTTP:

{
  "mcpServers": {
    "sapient": {
      "url": "http://sap-windows-machine:8765/mcp"
    }
  }
}

Isso funciona de forma idêntica no Claude Desktop, Claude Code, Cursor, VS Code, Windsurf e qualquer outro cliente compatível com MCP.

Opção C — Arquivo de configuração

python -m sapient_mcp --config C:\sap_config.json

Variáveis de Ambiente

Todas as configurações podem ser fornecidas como variáveis de ambiente com o prefixo ROBOSAP_MCP_:

Variável	Padrão	Descrição
`ROBOSAP_MCP_SAPLOGON_PATH`	`C:\...\saplogon.exe`	Caminho para o executável do SAP Logon
`ROBOSAP_MCP_SAP_SERVER`	`null`	Descrição do servidor para conexão automática
`ROBOSAP_MCP_SAP_CLIENT`	`null`	Cliente SAP para login automático
`ROBOSAP_MCP_SAP_USER`	`null`	Usuário SAP para login automático
`ROBOSAP_MCP_SAP_PASSWORD`	`null`	Senha SAP (nunca registrada em log)
`ROBOSAP_MCP_PORT`	`null` (stdio)	Porta para modo SSE
`ROBOSAP_MCP_CAPS`	`""`	Capacidades separadas por vírgula: screenshot,codegen,advanced
`ROBOSAP_MCP_OUTPUT_DIR`	`./sap_output`	Diretório de capturas de tela e logs
`ROBOSAP_MCP_SCREENSHOT_ON_ERROR`	`true`	Captura automática de tela em falhas de ferramentas

Ferramentas Disponíveis

Núcleo (sempre carregado)

Ferramenta	Descrição
`sap_open`	Iniciar SAP Logon
`sap_connect_to_server`	Conectar ao servidor SAP
`sap_connect_to_running`	Anexar à sessão SAP em execução
`sap_get_session_info`	Somente leitura: estado atual e título
`sap_close`	Fechar SAP
`sap_execute_transaction`	Executar um código de transação
`sap_activate_tab`	Clicar em uma aba pelo rótulo
`sap_get_window_title`	Somente leitura: título da janela atual
`sap_select_menu_item`	Navegar na barra de menus
`sap_send_key`	Enviar tecla do teclado (Enter, F3, etc.)
`sap_fill_text_field`	Preencher um campo pelo seu rótulo
`sap_clear_text_field`	Limpar um campo
`sap_set_checkbox`	Marcar uma caixa de seleção
`sap_unset_checkbox`	Desmarcar uma caixa de seleção
`sap_select_radio_button`	Selecionar um botão de opção
`sap_push_button`	Clicar em um botão pelo rótulo
`sap_button_exists`	Somente leitura: verificar se o botão existe
`sap_read_text_field`	Somente leitura: ler valor do campo
`sap_read_text`	Somente leitura: ler qualquer elemento de texto
`sap_read_status_bar`	Somente leitura: mensagem da barra de status do SAP
`sap_count_table_rows`	Somente leitura: contagem de linhas da tabela
`sap_select_table_row`	Selecionar uma linha da tabela
`sap_read_table_cell`	Somente leitura: ler valor de uma célula
`sap_fill_cell`	Preencher uma célula da tabela
`sap_double_click_cell`	Duplo clique em uma célula da tabela
`sap_scroll_table`	Rolar tabela para cima/baixo

`--caps screenshot`

Ferramenta	Descrição
`sap_take_screenshot`	Capturar captura de tela da janela SAP

`--caps codegen`

Ferramenta	Descrição
`sap_get_generated_script`	Obter script Robot Framework acumulado
`sap_clear_script`	Limpar buffer de script

`--caps advanced`

Ferramenta	Descrição
`sap_get_snapshot`	Instantâneo JSON estruturado da janela atual

Exemplo de Conversa com LLM

Você: Crie um pedido de compra para o fornecedor 100001, código da empresa 1000, com 50 unidades do material ABC-001

O SAPient guiará o LLM para:

Chamar sap_execute_transaction("/nME21N")
Chamar sap_get_window_title() → "Criar Pedido de Compra"
Chamar sap_fill_text_field("Vendor", "100001")
Chamar sap_fill_text_field("Company Code", "1000")
Chamar sap_send_key("Enter") para aceitar o cabeçalho
Chamar sap_activate_tab("Item Overview")
Chamar sap_fill_cell("1", "Material", "ABC-001")
Chamar sap_fill_cell("1", "Quantity", "50")
Chamar sap_push_button("Save")
Chamar sap_read_status_bar() → "Pedido de compra 4500001234 criado"

Estrutura do Projeto

sapient-mcp/
├── pyproject.toml
├── README.md
├── sap_config.json              # Example config file
├── claude_desktop_config.json   # Example Claude Desktop config
└── src/
    └── sapient_mcp/
        ├── __init__.py
        ├── __main__.py          # Entry point + CLI arg parsing
        ├── config.py            # Pydantic settings (env/file/CLI)
        ├── session.py           # SAPSessionManager singleton
        └── server.py            # FastMCP server + all 27 tool definitions

Logs

Os logs são gravados em {output_dir}/sapient_mcp.log.

No modo stdio, os logs nunca vão para stdout/stderr (quebraria o JSON-RPC). No modo SSE, os logs também aparecem no stderr.