Hana MCP Server README

SAP HANA MCP Server

SAP HANA MCP Server implements the Model Context Protocol for SAP HANA and SAP HANA Cloud. AI clients discover schema, run SQL with guardrails, and optionally merge business/domain metadata so agents interpret codes and tables consistently—without replacing your database as the system of record.

📚 Documentation

✅ Prerequisites

• Node.js 18+
• A SAP HANA or SAP HANA Cloud database reachable on the SQL port from the machine running the server
• An MCP client (Claude Desktop, Claude Code, VS Code, Cursor, Cline, Windsurf, or custom HTTP client)
• Credentials supplied via env (see Security)

📦 Installation

HTTP entrypoint (from a clone): npm run start:http — default bind 127.0.0.1:3100, path /mcp. See Hosted & HTTP.

🎯 Use cases

🖥️ Claude Desktop

1. Config file path:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\claude\claude_desktop_config.json
   • Linux: ~/.config/claude/claude_desktop_config.json

2. Register the server; put connection settings in env (see Configuration; full profile JSON in configuration-samples.md). The example below includes HANA_INSTANCE_NUMBER / HANA_DATABASE_NAME for MDC—remove them if you use a single-container database.

{
  "mcpServers": {
    "HANA Database": {
      "command": "npx",
      "args": ["-y", "hana-mcp-server"],
      "env": {
        "HANA_HOST": "your-hana-host.com",
        "HANA_PORT": "443",
        "HANA_USER": "your-username",
        "HANA_PASSWORD": "your-password",
        "HANA_SCHEMA": "your-schema",
        "HANA_SSL": "true",
        "HANA_ENCRYPT": "true",
        "HANA_VALIDATE_CERT": "true",
        "HANA_CONNECTION_TYPE": "auto",
        "HANA_INSTANCE_NUMBER": "10",
        "HANA_DATABASE_NAME": "HQQ",
        "LOG_LEVEL": "info",
        "ENABLE_FILE_LOGGING": "true",
        "ENABLE_CONSOLE_LOGGING": "false"
      }
    }
  }
}

If the CLI is on PATH, you may use "command": "hana-mcp-server" and omit args.

3. Restart Claude Desktop.

Optional: HANA MCP UI — npx hana-mcp-ui for editing envs and deploying to Claude Desktop.

💻 IDEs & code agents

stdio only; same env keys as above. Canonical example — Claude Code (~/.claude.json or project .mcp.json). The env block below includes HANA_DATABASE_NAME for MDC tenant HANA; omit it for most single-container setups.

{
  "mcpServers": {
    "hana": {
      "type": "stdio",
      "timeout": 600,
      "command": "npx",
      "args": ["-y", "hana-mcp-server"],
      "env": {
        "HANA_HOST": "<host>",
        "HANA_PORT": "31013",
        "HANA_USER": "<user>",
        "HANA_PASSWORD": "<password>",
        "HANA_SCHEMA": "SAPABAP1",
        "HANA_DATABASE_NAME": "HQQ",
        "HANA_SSL": "false",
        "HANA_ENCRYPT": "false",
        "HANA_VALIDATE_CERT": "false",
        "LOG_LEVEL": "info",
        "ENABLE_FILE_LOGGING": "true",
        "ENABLE_CONSOLE_LOGGING": "false"
      }
    }
  }
}

Use the same command, args, and env in VS Code, Cline, Cursor, and Windsurf. After any change to env, restart the MCP server connection in the IDE.

🌐 Hosted & HTTP

Run the HTTP transport from a checkout of this repository (after npm install). The published npx hana-mcp-server path is stdio only.

npm run start:http

Cursor / local IDE over HTTP: set HANA_* in the shell (or process manager) that runs start:http, then add an HTTP MCP entry with url http://127.0.0.1:3100/mcp ("type": "fetch" or "type": "http", depending on Cursor version). See docs/local-http-mcp.md and ./scripts/start-http-mcp.sh.

Optional Bearer JWT (OAuth2 / OIDC)

SAP BTP: bind XSUAA, MCP_HTTP_AUTH_ENABLED=true, assign role collections. Details: ENVIRONMENT.md §7.

🔒 Security

• Secrets: HANA_PASSWORD, JWT material, and URLs with embedded credentials belong in env or a secret manager — not in git.
• Supply chain: Prefer npx -y from the published package in CI and shared desktops instead of a mutable global install.
• HTTP: Enable JWT validation for anything beyond localhost; put the service behind a reverse proxy for TLS termination and network policy.

Further notes: ENVIRONMENT.md §9.

🎯 Capabilities

34 tools across six areas, all verified on HANA Cloud.

🛠️ Configuration

Variables apply to stdio (env in the client config) and HTTP (process environment). Restart after changes.

Source of truth for names, defaults, and clamp ranges: docs/ENVIRONMENT.md.
Copy-paste connection JSON (single-container / MDC): docs/configuration-samples.md#connection-profiles-env-json.

Required

Connection & TLS

Logging

*Code default; examples frequently set file logging to true.

Limits (queries, lists, resources)

DML permissions

INSERT, UPDATE, and DELETE are blocked by default. Set each to true to permit:

Business / domain JSON (HANA_SEMANTICS_*)

Samples: configuration-samples.md.

🔧 Troubleshooting

Debug: LOG_LEVEL=debug, ENABLE_CONSOLE_LOGGING=true, restart.

Client cannot find npx (spawn ENOENT)

GUI clients launched from the Dock or Start Menu (Claude Desktop, Cursor, VS Code, …) inherit a minimal PATH and may not see Node tooling installed under /opt/homebrew/bin, ~/.nvm/..., mise, or volta. This affects every npx-based MCP, not just this server. The error appears in MCP client logs as:

Connection failed: spawn npx ENOENT

Pick one fix:

1. Symlink npx / node into a GUI-visible path (macOS, Homebrew):

   bashCopy

   ln -s "$(which npx)"  /usr/local/bin/npx
   ln -s "$(which node)" /usr/local/bin/node
   

2. Use absolute paths in the MCP config — most portable, no PATH dependency. Resolve paths with which node and npm root -g:

   config.jsonCopy

   {
     "mcpServers": {
       "hana": {
         "type": "stdio",
         "command": "/opt/homebrew/bin/node",
         "args": ["/opt/homebrew/lib/node_modules/hana-mcp-server/hana-mcp-server.js"],
         "env": { "HANA_HOST": "...", "HANA_USER": "...", "HANA_PASSWORD": "..." }
       }
     }
   }
   

   Requires a one-time npm install -g hana-mcp-server.

3. Inject PATH into the MCP env block — keeps the npx form:

   jsonCopy

   "env": {
     "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
     "HANA_HOST": "...",
     "HANA_USER": "...",
     "HANA_PASSWORD": "..."
   }
   

Restart the MCP client after the change. If npx then fails with EPERM on ~/.npm/_cacache, the npm cache has root-owned files from a previous sudo npm — fix with sudo chown -R "$(whoami)" ~/.npm or set "NPM_CONFIG_CACHE": "/tmp/hana-mcp-npm-cache" in the same env block.

🖥️ HANA MCP UI

npx hana-mcp-ui

🏗️ Architecture

hana-mcp-server/
├── src/
│   ├── server/           # MCP lifecycle, resources, HTTP transport
│   ├── tools/            # 34 tools: schema, SQL, discovery, config
│   ├── database/         # HANA client, connection pool, executor, query runner
│   ├── semantics/        # Optional semantics / domain JSON loader
│   ├── utils/            # Logger, config, validators, formatters
│   ├── query-snapshot-store.js
│   └── constants/        # MCP constants, tool definitions
├── tests/
├── docs/                 # README index, ENVIRONMENT.md, configuration-samples.md, diagrams
└── hana-mcp-server.js    # stdio entry point

📦 Package

🤝 Support

• Issues: GitHub Issues
• UI: HANA MCP UI

📄 License

MIT — see LICENSE.