Skip to main content
Glama
HANA Cloud MCP Server

HANA Cloud MCP Server

by HatriGt

SAP HANA MCP 服务器

npm version npm downloads Node.js License MCP

SAP HANA MCP 服务器 为 SAP HANA 和 SAP HANA Cloud 实现了 模型上下文协议 (Model Context Protocol)。AI 客户端可以发现模式、在防护机制下运行 SQL,并可选择合并 业务/领域元数据,以便代理能够一致地解释代码和表——而无需替换您作为记录系统的数据库。


📚 文档

文档

用途

本 README

先决条件、安装、如何连接各客户端、功能摘要、配置速查表、故障排除

CHANGELOG.md

发布历史 — 按版本划分的功能和修复 (0.2.x, 最新版 0.2.2)

docs/README.md

/docs 索引

docs/ENVIRONMENT.md

权威环境变量参考:每个变量、默认值、硬性限制、HTTP 认证、安全说明

docs/configuration-samples.md

复制粘贴:连接配置文件(单容器、MDC)、语义 JSON、分页指针

docs/local-http-mcp.md

本地 HTTP MCP:npm run start:http,Cursor mcp.json,curl 冒烟测试


Related MCP server: mcp4odata

✅ 先决条件

  • Node.js 18+

  • 一台从运行服务器的机器上可以通过 SQL 端口访问的 SAP HANA 或 SAP HANA Cloud 数据库

  • 一个 MCP 客户端 (Claude Desktop, Claude Code, VS Code, Cursor, Cline, Windsurf 或自定义 HTTP 客户端)

  • 通过环境变量提供的 凭据 (参见 安全)


📦 安装

方法

使用场景

MCP 配置中的 npx + -y hana-mcp-server

默认 — 无需全局安装

npm install -g hana-mcp-server

您需要在 PATH 中使用 hana-mcp-server

克隆 + node hana-mcp-server.js

开发或固定本地构建版本

HTTP 入口点 (从克隆版本):npm run start:http — 默认绑定 127.0.0.1:3100,路径 /mcp。参见 托管与 HTTP。


🎯 使用场景

受众

传输方式

下一步

聊天 / 轻量用户

stdio

Claude Desktop

开发人员 (Claude Code, VS Code, Cline, Cursor, Windsurf)

stdio

IDE 与代码代理

带有 AI 代理的业务应用 (您通过 HTTP 托管 MCP)

HTTP

托管与 HTTP


🖥️ Claude Desktop

  1. 配置文件路径:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\claude\claude_desktop_config.json

    • Linux: ~/.config/claude/claude_desktop_config.json

  2. 注册服务器;将连接设置放入 env (参见 配置;完整配置 JSON 见 configuration-samples.md)。下面的示例包含了用于 MDC 的 HANA_INSTANCE_NUMBER / HANA_DATABASE_NAME — 如果您使用单容器数据库,请移除它们。

{
  "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"
      }
    }
  }
}

如果 CLI 在 PATH 中,您可以使用 "command": "hana-mcp-server" 并省略 args。

  1. 重启 Claude Desktop。

可选: HANA MCP UI — 使用 npx hana-mcp-ui 编辑环境变量并部署到 Claude Desktop。


💻 IDE 与代码代理

仅限 stdio;使用与上述相同的 env 键。规范示例 — Claude Code (~/.claude.json 或项目 .mcp.json)。下面的 env 块包含了用于 MDC 租户 HANA 的 HANA_DATABASE_NAME;对于大多数单容器设置,请省略它。

{
  "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"
      }
    }
  }
}

在 VS Code, Cline, Cursor 和 Windsurf 中使用相同的 command, args 和 env。在对 env 进行任何更改后,请在 IDE 中重启 MCP 服务器连接。


🌐 托管与 HTTP

从本仓库的检出版本中运行 HTTP 传输 (在 npm install 之后)。已发布的 npx hana-mcp-server 路径仅支持 stdio。

npm run start:http

通过 HTTP 使用 Cursor / 本地 IDE: 在运行 start:http 的 shell (或进程管理器) 中设置 HANA_*,然后添加一个 HTTP MCP 条目,其 url 为 http://127.0.0.1:3100/mcp ("type": "fetch" 或 "type": "http",取决于 Cursor 版本)。参见 docs/local-http-mcp.md 和 ./scripts/start-http-mcp.sh。

主题

详情

端点

POST JSON-RPC 到 /mcp (默认基础路径 http://127.0.0.1:3100)

调优

MCP_HTTP_HOST, MCP_HTTP_PORT

健康检查

GET /health → 200

CORS

MCP_HTTP_ALLOWED_ORIGINS — ENVIRONMENT.md §7

可选 Bearer JWT (OAuth2 / OIDC)

变量

角色

MCP_HTTP_AUTH_ENABLED

true → 在 POST /mcp 上要求 Authorization: Bearer <token>

MCP_HTTP_JWT_ISSUER

颁发者 / JWKS (在绑定了 XSUAA 的 SAP BTP 上省略)

MCP_HTTP_JWT_AUDIENCE

可选的预期 aud

MCP_HTTP_JWT_SCOPES_REQUIRED

可选的作用域列表

SAP BTP: 绑定 XSUAA,设置 MCP_HTTP_AUTH_ENABLED=true,并分配角色集合。详情:ENVIRONMENT.md §7。


🔒 安全

  • 密钥: HANA_PASSWORD、JWT 材料以及带有嵌入式凭据的 URL 应放在环境变量或密钥管理器中 — 不要放入 git。

  • 供应链: 在 CI 和共享桌面中,优先使用已发布包的 npx -y,而不是可变的全局安装。

  • HTTP: 对于 localhost 以外的任何内容,请启用 JWT 验证;将服务置于反向代理之后以进行 TLS 终止和网络策略控制。

更多说明:ENVIRONMENT.md §9。


🎯 功能

领域

调用者获得什么

模式

分页的模式/表列表、列元数据、连接检查

SQL

参数化执行;对 SELECT/WITH 的行数、列数和单元格大小的限制;在支持的情况下通过 hana_query_next_page 进行总计和延续

资源

用于列表/读取的 hana:/// URI;带有 truncated 元数据标记的大型负载

领域知识 (可选)

用于 hana_explain_table 的 JSON 覆盖层 — configuration-samples.md


🛠️ 配置

变量适用于 stdio (客户端配置中的 env) 和 HTTP (进程环境变量)。更改后请重启。

名称、默认值和限制范围的权威来源: docs/ENVIRONMENT.md。 复制粘贴连接 JSON (单容器 / MDC): docs/configuration-samples.md#connection-profiles-env-json。

必需

参数

描述

示例

HANA_HOST

主机名或 IP

hana.company.com

HANA_USER

数据库用户

DBADMIN

HANA_PASSWORD

数据库密码

(密钥)

连接与 TLS

参数

默认值

说明

HANA_PORT

443

MDC SQL 端口通常为 3NN13 (例如 31013)

HANA_SCHEMA

—

工具省略 schema_name 时的默认值

HANA_CONNECTION_TYPE

auto

auto, single_container, mdc_system, mdc_tenant

HANA_INSTANCE_NUMBER

—

MDC 实例 ID (例如 10)

HANA_DATABASE_NAME

—

MDC 的 租户 名称 (例如 HQQ, HQP) — 仅限会话数据库

HANA_SSL / HANA_ENCRYPT / HANA_VALIDATE_CERT

true

驱动程序的 TLS 和证书验证标志

日志记录

参数

默认值

说明

LOG_LEVEL

info

error … debug

ENABLE_FILE_LOGGING

false*

true 启用文件日志

ENABLE_CONSOLE_LOGGING

true

对于 stdio,通常设为 false 以减少 stderr 噪音

*代码默认值;示例通常将文件日志记录设置为 true。

限制 (查询、列表、资源)

参数

默认值

用途

HANA_MAX_RESULT_ROWS

50

每个 hana_execute_query 页面的最大行数 (SELECT/WITH)

HANA_MAX_RESULT_COLS

50

每行返回的最大列数

HANA_MAX_CELL_CHARS

200

截断过长的单元格文本

HANA_QUERY_DEFAULT_OFFSET

0

默认 offset

HANA_LIST_DEFAULT_LIMIT

200

列表工具:默认和最大页面大小

HANA_RESOURCE_LIST_MAX_ITEMS

500

hana:/// 负载中嵌入名称的上限

HANA_QUERY_SNAPSHOT_TTL_MS

300000

查询分页的快照 ID 生命周期

业务 / 领域 JSON (HANA_SEMANTICS_*)

参数

默认值

用途

HANA_SEMANTICS_PATH

—

字典 JSON 的文件路径 (优先级高于 URL)

HANA_SEMANTICS_URL

—

相同格式的 HTTPS URL

HANA_SEMANTICS_TTL_MS

60000

缓存 / 重新加载行为

示例:configuration-samples.md。


🔧 故障排除

症状

检查

连接被拒绝

HANA_HOST, HANA_PORT, 网络路径

认证失败 / 无客户端

密码、用户、租户上的 HANA_DATABASE_NAME;使用连接测试工具查看驱动程序消息

TLS 错误

HANA_VALIDATE_CERT, 信任存储

对象错误或为空

MDC:租户决定可见性;相同的模式名称在不同租户下可能不同

SQL 需要另一个数据库前缀

hana_execute_query 不会重写 SQL;使用 HANA 预期的三部分名称 (例如 HSP.SAPABAP1.TABLE),同时 HANA_DATABASE_NAME 保持为您连接的租户 (例如 HQP)

调试: LOG_LEVEL=debug, ENABLE_CONSOLE_LOGGING=true, 重启。


🖥️ HANA MCP UI

npx hana-mcp-ui

HANA MCP UI


🏗️ 架构

HANA MCP 服务器架构

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

📦 包

运行时

Node.js 18+

平台

macOS, Linux, Windows

依赖

@sap/hana-client, axios, jose


🤝 支持

📄 许可证

MIT — 参见 LICENSE。

Available Tools

9 tools
hana_describe_indexC

Describe the structure of a specific index

Inputs: table_name (required), index_name (required), schema_name.

hana_describe_tableC

Describe the structure of a specific table

Inputs: table_name (required), schema_name.

hana_execute_queryC

Execute a custom SQL query against the HANA database

Inputs: query (required), parameters.

hana_list_indexesC

List all indexes for a specific table

Inputs: table_name (required), schema_name.

hana_list_schemasB

List all schemas in the HANA database

Inputs: no named parameters.

hana_list_tablesC

List all tables in a specific schema

Inputs: schema_name.

hana_show_configB

Show the HANA database configuration

Inputs: no named parameters.

hana_show_env_varsB

Show all HANA-related environment variables (for debugging)

Inputs: no named parameters.

hana_test_connectionB

Test connection to HANA database

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific database operations like describing structures, listing resources, executing queries, or showing configuration. There is no overlap in functionality that would cause confusion between tools.

    Naming Consistency5/5

    All tools follow a consistent 'hana_verb_noun' pattern with snake_case throughout, using clear verbs like describe, list, execute, show, and test. This predictable naming makes the tool set easy to navigate and understand.

    Tool Count5/5

    With 9 tools, this server is well-scoped for database interaction, covering essential operations like connection testing, schema exploration, query execution, and configuration viewing. Each tool earns its place without feeling excessive or insufficient.

    Completeness4/5

    The tool set provides strong coverage for database exploration and querying, including CRUD-like operations via custom SQL. Minor gaps exist, such as no explicit tools for creating or modifying database objects, but agents can work around this using the execute_query tool for most needs.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes SAP S/4HANA OData services as tools for LLMs, enabling users to list and create sales orders via the Model Context Protocol. It integrates with SAP BTP using the SAP Cloud SDK to provide secure access to enterprise data through natural language.
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query, analyze, and manage SQL Server databases through natural language via the Model Context Protocol.
      6
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that enables AI assistants like Claude to work directly inside SAP BW/4HANA systems — reading, creating and modifying BW modeling objects via the internal REST API used by Eclipse BWMT.
      MIT