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

Document	Purpose
This README	Prerequisites, install, how to wire each client, capability summary, configuration cheat sheet, troubleshooting
CHANGELOG.md	Release history — features and fixes by version (0.2.x, latest 0.2.2)
docs/README.md	Index of /docs
docs/ENVIRONMENT.md	Authoritative env reference: every variable, defaults, hard bounds, HTTP auth, security notes
docs/configuration-samples.md	Copy-paste: connection profiles (single-container, MDC), semantics JSON, paging pointers
docs/local-http-mcp.md	Local HTTP MCP: npm run start:http, Cursor mcp.json, curl smoke checks

---

✅ 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

Method	Use when
npx + -y hana-mcp-server in MCP config	Default — no global install
npm install -g hana-mcp-server	You need hana-mcp-server on PATH
Clone + node hana-mcp-server.js	Developing or pinning a local build

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

---

🎯 Use cases

Audience	Transport	Next step
Chat / lite users	stdio	Claude Desktop
Developers (Claude Code, VS Code, Cline, Cursor, Windsurf)	stdio	IDEs & code agents
Business apps with AI agents (you host MCP over HTTP)	HTTP	Hosted & HTTP

---

🖥️ 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.

Topic	Detail
Endpoint	POST JSON-RPC to /mcp (default base http://127.0.0.1:3100)
Tuning	MCP_HTTP_HOST, MCP_HTTP_PORT
Health	GET /health → 200
CORS	MCP_HTTP_ALLOWED_ORIGINS — ENVIRONMENT.md §7

Optional Bearer JWT (OAuth2 / OIDC)

Variable	Role
MCP_HTTP_AUTH_ENABLED	true → require Authorization: Bearer <token> on POST /mcp
MCP_HTTP_JWT_ISSUER	Issuer / JWKS (omit on SAP BTP with bound XSUAA)
MCP_HTTP_JWT_AUDIENCE	Optional expected aud
MCP_HTTP_JWT_SCOPES_REQUIRED	Optional scope list

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

Area	What callers get
Schema	Paged schema/table lists, column metadata, connectivity checks
SQL	Parameterized execution; caps on SELECT/WITH rows, columns, and cell size; optional totals and continuation via hana_query_next_page where supported
Resources	hana:/// URIs for list/read; large payloads flagged with truncated metadata
Domain knowledge (optional)	JSON overlay for hana_explain_table — configuration-samples.md

---

🛠️ 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

Parameter	Description	Example
HANA_HOST	Hostname or IP	hana.company.com
HANA_USER	Database user	DBADMIN
HANA_PASSWORD	Database password	(secret)

Connection & TLS

Parameter	Default	Notes
HANA_PORT	443	MDC SQL ports often 3NN13 (e.g. 31013)
HANA_SCHEMA	—	Default when a tool omits schema_name
HANA_CONNECTION_TYPE	auto	auto, single_container, mdc_system, mdc_tenant
HANA_INSTANCE_NUMBER	—	MDC instance id (e.g. 10)
HANA_DATABASE_NAME	—	Tenant name for MDC (e.g. HQQ, HQP) — session database only
HANA_SSL / HANA_ENCRYPT / HANA_VALIDATE_CERT	true	TLS and cert validation flags for the driver

Logging

Parameter	Default	Notes
LOG_LEVEL	info	error … debug
ENABLE_FILE_LOGGING	false*	true enables file logs
ENABLE_CONSOLE_LOGGING	true	Often false for stdio to reduce stderr noise

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

Limits (queries, lists, resources)

Parameter	Default	Purpose
HANA_MAX_RESULT_ROWS	50	Max rows per hana_execute_query page (SELECT/WITH)
HANA_MAX_RESULT_COLS	50	Max columns per row returned
HANA_MAX_CELL_CHARS	200	Truncate long cell text
HANA_QUERY_DEFAULT_OFFSET	0	Default offset
HANA_LIST_DEFAULT_LIMIT	200	List tools: default and max page size
HANA_RESOURCE_LIST_MAX_ITEMS	500	Cap embedded names in hana:/// payloads
HANA_QUERY_SNAPSHOT_TTL_MS	300000	Snapshot id lifetime for query paging

Business / domain JSON (HANA_SEMANTICS_*)

Parameter	Default	Purpose
HANA_SEMANTICS_PATH	—	File path to dictionary JSON (wins over URL)
HANA_SEMANTICS_URL	—	HTTPS URL to same format
HANA_SEMANTICS_TTL_MS	60000	Cache / reload behavior

Samples: configuration-samples.md.

---

🔧 Troubleshooting

Symptom	Check
Connection refused	HANA_HOST, HANA_PORT, network path
Auth failed / no client	Password, user, HANA_DATABASE_NAME on tenants; use connection test tool for driver message
TLS errors	HANA_VALIDATE_CERT, trust store
Wrong or empty objects	MDC: tenant drives visibility; identical schema names can differ by tenant
SQL needs another database prefix	hana_execute_query does not rewrite SQL; use the three-part names your HANA expects (e.g. HSP.SAPABAP1.TABLE) while HANA_DATABASE_NAME stays the tenant you connect to (e.g. HQP)

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

---

🖥️ HANA MCP UI

npx hana-mcp-ui

---

🏗️ Architecture

hana-mcp-server/
├── src/
│   ├── server/           # MCP lifecycle, resources, HTTP transport
│   ├── tools/            # Schema, table, query, index, config tools
│   ├── database/         # HANA client, connection manager, 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

Runtime	Node.js 18+
Platforms	macOS, Linux, Windows
Dependencies	@sap/hana-client, axios, jose

---

🤝 Support

• Issues: GitHub Issues
• UI: HANA MCP UI

📄 License

MIT — see LICENSE.