sap-b1-hana-mcp

MCP (Model Context Protocol) server for querying SAP B1 HANA using direct SQL through SAP's official driver (@aps/ana-driver).

No installation required: it runs with npx directly from this GitHub repository. You only need to define environment variables.

Usage

1. Requirements

• Node.js 20+ (only on the machine running the agent; nothing from the MCP is installed).

2. Register in opencode (or another MCP client)

Add this block to your opencode configuration (for example ~/ .config/opencode/opencode.json):

{
  "mcp": {
    "sap-b1-hana": {
      "type": "local",
      "command": ["npx", "-y", "github:leonardows1/sap-b1-hana-mcp"],
"environment": {
        "HANA_HOST": "192.168.1.100",
        "HANA_PORT": "30015",
        "HANA_USER": "USUARIO_HANA",
        "HANA_PASSWORD": "TU_CONTRASEÑA",
        "HANA_DATABASE": "MI_TENANT",
        "HANA_SCHEMA": "MI_EMPRESA",
        "HANA_READONLY": "true"
      },
      "enabled": true
    }
  }
}

Note: the first time npx runs, it downloads and installs the package and may take more than 5 seconds. If the MCP client reports a timeout at startup, increase "timeout": 60000 in the block.

3. Environment variables

Related MCP server: SAP MCP Server

MCP tools

Important note about SQL and SAP B1

SAP B1 tables and columns use mixed capitalization and are case‑sensitive: column names must be written between double quotes:

SELECT "ItemCode", "ItemName", "OnHand" FROM OITM WHERE "OnHand" > 0 ORDER BY "OnHand" DESC

Without quotes, HANA converts to uppercase and the query fail with invalid column name.

Read‑only mode

With HANA_READONLY=true (default), the server will not accept any statement that is not SELECT, WITH, EXPLAIN, SHOW or DESCRIBE. To enable writes, use HANA_READONLY=false — at your own risk.

Development

npm install
npm run build      # compila TypeScript a dist/
npm test           # tests unitarios (vitest)

The dist/ folder is compiled and versioned: that is what runs when using npx github… without requiring a build on the user’s machine.

Architecture

Layers with manual dependency injection and SOLID principles:

src/
├── index.ts              Composition root: DI, host MCP (stdio)
├── configuration/        HanaOptions + validación de variables de entorno
├── domain/               Modelos: QueryResult, SchemaInfo, TableInfo, ColumnInfo, StatementKind
├── application/          Abstracciones de servicios + ISqlGuard (Strategy) + clasificador SQL
├── infrastructure/       Única capa que toca @sap/hana-client: factory de conexión,
│                         servicios de consulta/esquema, mapeo de datos (Buffer→base64, Date→ISO)
└── mcp/                  Adaptadores delgados: registro de tools MCP

Licenses

• This project: MIT.

• Driver @sap/hana-client: SAP Developer License Agreement (distributed through npm dependency, not versioned in this repository). See node_modules/@sap/hana-client/developer-license-3_2.txt.