HANA CLI

Appearance

MCP Server Usage & Setup ​

How to run and use the MCP (Model Context Protocol) server with HANA CLI.

Quick Start ​

Easiest: Auto-Configure ​

bash
# Auto-detect installed AI clients and configure them
hana-cli mcp

# Or target a specific client
hana-cli mcp --client claude-desktop
hana-cli mcp --client claude-code --global
hana-cli mcp --client cursor

Via npx (No Local Install) ​

Run the MCP server via npx — no global install or build step needed:

bash
npx -y -p hana-cli hana-cli-mcp

From Source (Development) ​

bash
# Navigate to mcp-server directory
cd mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

Running the Server ​

bash
# Start MCP server (listens on stdio)
node build/index.js

# With debug logging
DEBUG=hana-cli:* node build/index.js

# With larger heap for very large workloads
NODE_OPTIONS="--max-old-space-size=4096" node build/index.js

MCP Registry ​

The server is published to the MCP Registry as io.github.SAP-samples/hana-cli. AI clients that support the MCP Registry can discover and install it automatically.

How It Works ​

The MCP server:

  1. Receives tool calls from AI assistants (Claude, etc)
  2. Extracts parameters from the request
  3. Executes HANA CLI commands in Node.js
  4. Returns results in structured markdown format

Available Tools ​

The MCP server exposes 150+ HANA CLI tools:

Data Tools: import, export, compareData, dataProfile, dataDiff, dataValidator, dataMask, dataSync, duplicateDetection, dataLineage

Schema Tools: compareSchema, schemaClone, tableCopy, erdDiagram, generateDocs, generateTestData

Query Tools: querySimple, callProcedure, tables, views, functions, procedures, roles, etc

System Tools: backup, replicationStatus, partitions, spatialData, and more

Usage with AI Assistants ​

With Claude Desktop ​

  1. Configure claude_desktop_config.json:
json
{
  "mcpServers": {
    "hana-cli": {
      "command": "npx",
      "args": ["-y", "-p", "hana-cli", "hana-cli-mcp"]
    }
  }
}

Or run hana-cli mcp --client claude-desktop to configure automatically.

  1. Restart Claude Desktop
  2. Ask Claude questions about your HANA database

With VSCode (GitHub Copilot) ​

  1. Configure VSCode MCP Settings

    Edit your VSCode MCP configuration at ~/.config/Code/User/mcp.json (or find it in your User settings):

    json
    {
  "servers": {
    "io.github.SAP-samples/hana-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "hana-cli", "hana-cli-mcp"]
    }
  }
}

    Or if you have a local build, point directly to it:

    json
    {
  "servers": {
    "io.github.SAP-samples/hana-cli": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-server/build/index.js"
      ]
    }
  }
}

    Important Notes:

    • Use absolute paths when pointing to a local build
    • Use forward slashes / even on Windows

  2. Restart VSCode

    VSCode will automatically detect and load the MCP server

  3. Verify Installation

Open the VSCode output panel (View → Output), then select Copilot from the dropdown.

You should see messages like:

[MCP] Loaded ... command modules from hana-cli

[MCP] Registered ... unique commands with ... processed modules

[MCP] SAP HANA CLI MCP Server running on stdio

  1. Use with Copilot

    Ask Copilot questions about your HANA database:

    • "Show me all tables in my schema"
    • "Import CSV data into this table"
    • "Compare data between two tables"
    • Copilot will use the hana_* tools to answer

Tip: Use hana_search tool to search the full documentation for answers to complex questions.

With Custom AI Agents ​

javascript
const { exec } = require('child_process');

// Start MCP server
const server = exec('node mcp-server/build/index.js');

// Send tool call
server.stdin.write(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "tools/call",
  params: {
    name: "hana_tables",
    arguments: {
      schema: "MY_SCHEMA",
      __projectContext: {
        projectPath: "/path/to/project"
      }
    }
  }
}));

// Listen for results
server.stdout.on('data', (data) => {
  console.log('MCP Response:', JSON.parse(data));
});

Project Context ​

When calling MCP tools, pass project context to automatically detect connections:

json
{
  "schema": "MY_SCHEMA",
  "__projectContext": {
    "projectPath": "/absolute/path/to/project",
    "connectionFile": ".env"
  }
}

The MCP server will:

  1. Change to the project directory
  2. Look for .env, default-env.json, or connection files
  3. Execute the command using the project's database

See Connection Guide for details.

Output Format ​

All results are returned as markdown tables for easy reading:

markdown
| Column1 | Column2 | Column3 |
|---------|---------|---------|
| Value1  | Value2  | Value3  |

Error Handling ​

When a command fails, the error is returned with:

  • Error message
  • Command that failed
  • Debug information (if available)
  • Suggestions for fixes

Example:

text
Error: Schema MY_SCHEMA not found
Command: hana_tables --schema MY_SCHEMA
Try: Check schema name is correct and you have permissions

Advanced Configuration ​

Environment Variables ​

  • DEBUG=hana-cli:* - Enable debug logging
  • HANA_CLI_PROJECT_PATH - Default project directory
  • HANA_CLI_CONN_FILE - Default connection file

Performance Tuning ​

  • Increase node heap: NODE_OPTIONS="--max-old-space-size=4096" node build/index.js
  • Use connection pooling for multiple queries
  • Batch operations for better performance

Troubleshooting ​

See MCP Troubleshooting for common issues.

See Also ​