Servidor MCP S/4HANA

Un servidor MCP que expone 38 herramientas para SAP S/4HANA (Cloud Public Edition y on-premise Private Edition) a través de OData V2, OData V4 y SOAP: socios comerciales, productos, precios de venta, almacenes, pedidos de compra, registros de información de compras, facturas de proveedores (incluyendo contabilización y anulación), hojas de entrada de servicios, asientos de diario, centros de coste y estructura organizativa de finanzas.

Las herramientas de escritura (create_*, cancel_supplier_invoice, check_invoice_posting_readiness) y get_finance_structure devuelven su resultado en línea como JSON. Cualquier otra herramienta (de lectura) escribe su resultado — CSV para colecciones, Markdown para registros individuales — en un sandbox E2B y devuelve la(s) ruta(s) de archivo, en lugar de incluir en línea conjuntos de resultados SAP potencialmente grandes (cientos de socios comerciales, detalle completo de partidas de asientos de diario, etc.) directamente en el contexto del agente llamante. Este servidor solo se conecta a un sandbox E2B que tu cliente MCP ya posee — nunca crea uno. Tu cliente necesita su propia integración E2B (el SDK de E2B, o un entorno Claude con acceso de ejecución de código coincidente) para leer los archivos de vuelta; consulta Configuración del sandbox E2B.

Inicio rápido

git clone https://github.com/ilia-inovaflow/s4hana-mcp-server.git
cd s4hana-mcp-server
npm install
npm run build
cp .env.example .env   # fill in your E2B sandbox + SAP connection details
npm start               # stdio transport (Claude Desktop, MCP Inspector, etc.)

Para desarrollo local sin compilar primero: npm run dev.

Related MCP server: SAP OData MCP Server

Configuración del sandbox E2B

Regístrate para obtener una clave API gratuita en e2b.dev, luego inicia (o reutiliza) un sandbox del que tu cliente MCP pueda leer archivos, y establece:

E2B_API_KEY=<your E2B API key>
SANDBOX_ID=<an already-running sandbox ID>   # stdio only — HTTP takes this per-session

Sobre el transporte HTTP, SANDBOX_ID se suministra por sesión en su lugar, mediante la cabecera de solicitud sandbox-id — útil cuando una instancia de servidor en ejecución maneja múltiples llamantes, cada uno con su propio sandbox.

Esto no está relacionado con el host de prueba sandbox.api.sap.com de SAP que aparece más abajo — "sandbox" significa dos cosas diferentes en este README.

Pruébalo sin un tenant SAP propio

SAP publica un sandbox de API público, gratuito y de solo lectura en sandbox.api.sap.com con el que este servidor se comunica de forma inmediata. Regístrate para obtener una clave API gratuita en api.sap.com, luego establece:

SAP_HOST=https://sandbox.api.sap.com
SAP_CLIENT_ID=<your sandbox API key>

No se necesita nombre de usuario, contraseña ni configuración OAuth — el sandbox se autentica con una única cabecera APIKey. Las herramientas de socios comerciales, productos y precios funcionan inmediatamente contra los datos de demostración del sandbox (aún necesitas el sandbox E2B de arriba para recibir los resultados de las herramientas de lectura).

Conexión a un tenant SAP real

Establece SAP_HOST a la URL de tu tenant y elige uno de los tres modos de autenticación mediante SAP_AUTH_MODE:

SAP_CLIENT (el número de cliente/mandante SAP, p. ej. 100) se establece por defecto a 100 si no se define.

Dos familias de API necesitan autenticación básica o X.509 por diseño de SAP y rechazan OAuth: la contabilización de asientos de diario (create_journal_entry, SOAP SAP_COM_0002) y las vistas de detalle de documentos contables (get_journal_entry, search_journal_entries con document_level=true). Todo lo demás funciona bajo cualquiera de los tres modos.

Consulta .env.example para la lista completa de variables, incluida la anulación opcional SAP_JE_SOAP_PATH que algunas configuraciones SOAMANAGER on-premise necesitan.

Transportes

stdio (por defecto, npm start / npm run dev) — una conexión SAP y un sandbox E2B por proceso, configurados completamente desde .env. Esto es lo que esperan Claude Desktop y la mayoría de los clientes MCP locales:

{
  "mcpServers": {
    "s4hana": {
      "command": "node",
      "args": ["/absolute/path/to/s4hana-mcp-server/dist/index.js"],
      "env": {
        "E2B_API_KEY": "...", "SANDBOX_ID": "...",
        "SAP_HOST": "...", "SAP_AUTH_MODE": "basic", "SAP_USERNAME": "...", "SAP_PASSWORD": "..."
      }
    }
  }
}

Streamable HTTP (npm run start:http / npm run dev:http) — para despliegue remoto o multi-tenant. La conexión SAP de cada sesión se configura desde los valores por defecto de .env o mediante cabeceras por solicitud (sap-host, sap-auth-mode, sap-username, sap-password, sap-token-url, sap-client-id, sap-client-secret, sap-client, sap-je-soap-path), y su sandbox E2B desde la cabecera sandbox-id (o la variable de entorno SANDBOX_ID como respaldo) — permitiendo que un único servidor en ejecución atienda solicitudes contra diferentes tenants y sandboxes. E2B_API_KEY siempre se lee del entorno del propio servidor. PORT (por defecto 3000) y HOST (por defecto localhost) configuran el listener; el endpoint MCP es POST /mcp, con GET /health para comprobaciones de disponibilidad.

Si despliegas el transporte HTTP en algún lugar accesible a través de la red, colócalo detrás de tu propio límite de autenticación/red — este servidor no controla por sí mismo el acceso al endpoint /mcp, solo a la conexión SAP descendente.

Herramientas

• search_business_partners — buscar clientes, proveedores, personas, organizaciones

• get_business_partner — detalle completo de un socio comercial

• query_business_partner_odata — consulta genérica contra cualquier conjunto de entidades de API_BUSINESS_PARTNER

• search_products — buscar materiales, productos terminados, servicios, materias primas

• get_product — detalle completo de un producto

• query_product_odata — consulta genérica contra cualquier conjunto de entidades de API_PRODUCT_SRV

• get_product_pricing — búsqueda de precio combinada para un material (empieza aquí para "cuánto cuesta X")

• search_pricing_conditions — explorar registros de condición por tipo/tasa

• get_pricing_condition — detalle completo de un registro de condición

• query_pricing_odata — consulta genérica contra cualquier conjunto de entidades de precios

• list_warehouses

• get_warehouse

• search_purchase_orders

• get_purchase_order

• query_purchase_order_odata — consulta genérica, incluido el nivel de partida/línea de programación

• get_purchase_order_confirmations — confirmaciones de pedido/envío/entrada de mercancías del proveedor, búsqueda masiva

• search_purchasing_info_records

• get_purchasing_info_record

• query_purchasing_info_record_odata

• search_supplier_invoices

• get_supplier_invoice

• query_supplier_invoice_odata

• create_supplier_invoice_po ⚠️ escritura — factura con referencia a pedido de compra, verificación de 3 vías

• create_supplier_invoice_gl ⚠️ escritura — factura de gasto sin pedido de compra, líneas de mayor directas

• create_supplier_credit_memo ⚠️ escritura — nota de crédito con referencia a pedido de compra

• cancel_supplier_invoice ⚠️ escritura — revierte una factura o nota de crédito contabilizada

• check_invoice_posting_readiness — comprobación previa de solo lectura

• search_service_entry_sheets

• get_service_entry_sheet

• query_service_entry_sheet_odata

• create_journal_entry ⚠️ escritura — contabiliza un documento de mayor (SOAP, solo autenticación básica/X.509)

• search_journal_entries — vista analítica (agregada) o de documento contable (nivel de partida)

• get_journal_entry — un documento contable por número

• search_gl_accounts

• search_open_po_items — las líneas de pedido de compra aún facturables de un proveedor, en una sola llamada

• search_cost_centers

• get_cost_center_hierarchy — el árbol de jerarquía de centros de coste estándar

• get_finance_structure — códigos de empresa, libros mayores, planes de cuentas, segmentos, áreas de negocio

Cada herramienta de escritura ejecuta comprobaciones de guardia en el servidor (existencia, indicadores de bloqueo, detección de duplicados, validación de saldo) antes de contabilizar y reporta una lista estructurada de razones — sin enviar nada a SAP — si alguna guardia falla. Los rechazos deterministas de SAP (períodos de contabilización cerrados, jurisdicción fiscal faltante, etc.) se traducen en mensajes accionables en lugar de códigos de error crudos.

Arquitectura

src/
├── server.ts       # McpServer factory — tool registration, schemas, annotations
├── client.ts        # SapClient — OData V2/V4 requests, CSRF-protected writes, SOAP posts
├── auth.ts           # Auth strategies: Basic, OAuth Client Credentials, OAuth Authorization Code
├── config.ts          # Connection config + SAP public sandbox detection
├── index.ts             # stdio entry point
├── http.ts               # Streamable HTTP entry point (Express, per-session auth)
└── tools/
    ├── shared.ts          # OData/CSV/error-parsing + E2B sandbox file I/O, shared by every tool
    └── *.ts                # one file per tool (schema + handler)

Las escrituras a endpoints OData V2 siguen el protocolo de token CSRF de SAP: obtener un token mediante GET con X-CSRF-Token: Fetch, reenviarlo con la cookie de sesión en el POST, reintentar una vez en un 403. La contabilización de asientos de diario, en cambio, construye y envía un sobre SOAP crudo, ya que esa API no tiene equivalente OData.

Desarrollo

npm run dev        # stdio, hot reload via tsx
npm run dev:http    # HTTP, hot reload via tsx
npm run typecheck    # tsc --noEmit
npm run build          # compile to dist/

Licencia

MIT