HANA Cloud MCP Server

SAP HANA MCP 服务

SAP HANA MCP Server 为 SAP HANA 和 SAP HANA Cloud 实现了 Model Context Protocol。AI 客户端可以发现架构、在防护措施下运行 SQL，并按需合并业务/领域元数据，帮助 Agent 一致地解读代码和表，而不会取代作为事实来源的数据库。

---

📚 文档

文档	用途
本 README	前提条件、安装、各客户端的连接方法、功能摘要、配置速查表、故障排除
CHANGELOG.md	发布历史——按版本列出的功能和修复（最新版本为 0.3.1）
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 冒烟测试

---

✅ 前提条件

• Node.js 18+
• 一台可从运行服务的机器通过 SQL 端口访问的 SAP HANA 或 SAP HANA Cloud 数据库
• 一个 MCP 客户端（Claude Desktop、Claude Code、VS Code、Cursor、Cline、Windsurf 或自定义 HTTP 客户端）
• 通过 env 提供的凭据（参见安全）

---

📦 安装

方法	适用场景
在 MCP 配置中使用 npx + -y hana-mcp-server	默认方式——无需全局安装
npm install -g hana-mcp-server	需要将 hana-mcp-server 添加到 PATH
克隆后运行 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 和编码 Agent
使用 AI Agent 的业务应用（通过 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。

3. 重启 Claude Desktop。

可选： HANA MCP UI——运行 npx hana-mcp-ui 以编辑 env 并部署到 Claude Desktop。

💻 IDE 和编码 Agent

仅支持 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（根据 Cursor 版本使用 "type": "fetch" 或 "type": "http"）。参见 docs/local-http-mcp.md 和 ./scripts/start-http-mcp.sh。

主题	详情
端点	向 /mcp 发送 POST JSON-RPC 请求（默认基址为 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 应存放在 env 或机密管理器中，而不是 git 中。
• **供应链：**在 CI 和共享桌面环境中，优先使用已发布软件包中的 npx -y，而不是可变的全局安装。
• **HTTP：**除 localhost 以外的场景都应启用 JWT 验证；将服务置于反向代理之后，以实现 TLS 终止和网络策略控制。

更多说明：ENVIRONMENT.md §9。

---

🎯 功能

34 个工具，涵盖六个领域，均已在 HANA Cloud 上验证。

领域	工具	功能
连接与配置	hana_show_config hana_test_connection hana_show_env_vars hana_get_session_info	验证连通性、检查配置、查看当前用户／架构／数据库／版本
架构浏览	hana_list_schemas hana_list_tables hana_describe_table hana_explain_table hana_search_tables hana_search_columns	分页列出架构／表、列元数据、跨架构搜索，以及可选的业务含义叠加信息
SQL 执行	hana_execute_query hana_query_next_page	参数化 SQL，支持可选的行／列／单元格上限、分页（maxRows／offset／includeTotal）和快照续查
结构分析	hana_list_constraints hana_list_foreign_keys hana_list_indexes hana_describe_index hana_list_views hana_describe_view hana_list_synonyms hana_list_privileges hana_get_ddl	PK／UK／FK／检查约束、索引、带 SQL 定义的视图、同义词、有效权限、CREATE 语句 DDL
代码对象	hana_list_procedures hana_describe_procedure hana_list_functions hana_describe_function hana_list_calculation_views hana_list_sequences	存储过程、标量／表函数、SAP BW/S4 计算视图（_SYS_BIC）、序列
数据与性能	hana_get_table_stats hana_get_sample_data hana_get_column_stats hana_explain_plan hana_get_dependencies hana_get_partition_info hana_get_expensive_queries	行数、样本行、不同值／空值统计、查询执行计划、对象依赖关系图、分区信息、开销最高的语句
DML 防护	—	默认阻止 INSERT / UPDATE / DELETE / TRUNCATE；可通过 HANA_ALLOW_INSERT / HANA_ALLOW_UPDATE / HANA_ALLOW_DELETE 分别选择启用
资源	hana:///schemas hana:///schemas/{s}/tables/{t}	用于列举架构和表的 MCP 资源 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_QUERY_LIMITS_ENABLED	false	设置为 true 可启用自动行数／列数／单元格上限。设置为 false 时，用户提供的 maxRows、offset 和 includeTotal 仍然有效。
HANA_QUERY_TIMEOUT_MS	0	语句超时时间（ms）；0 = 已禁用。单次调用的 timeout_ms 会覆盖此设置。
HANA_MAX_RESULT_ROWS	50	每个 hana_execute_query 分页的最大行数（启用限制后生效）
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 有效期
HANA_CONNECTION_POOL_SIZE	3	HANA 连接池大小（1–20）

DML 权限

默认禁止 INSERT、UPDATE 和 DELETE。将相应选项设为 true 即可允许：

参数	默认值	用途
HANA_ALLOW_INSERT	false	允许通过 hana_execute_query 执行 INSERT
HANA_ALLOW_UPDATE	false	允许通过 hana_execute_query 执行 UPDATE
HANA_ALLOW_DELETE	false	允许通过 hana_execute_query 执行 DELETE 和 TRUNCATE

业务／领域 JSON（HANA_SEMANTICS_*）

参数	默认值	用途
HANA_SEMANTICS_PATH	—	词典 JSON 的文件路径（优先于 URL）
HANA_SEMANTICS_URL	—	指向相同格式内容的 HTTPS URL
HANA_SEMANTICS_TTL_MS	60000	缓存／重新加载行为

示例：configuration-samples.md。

---

🔧 故障排除

症状	检查项
客户端日志中出现 spawn npx ENOENT / spawn hana-mcp-server ENOENT	客户端无法在 PATH 中找到 npx / hana-mcp-server——请参阅下文的客户端无法找到 npx
连接被拒绝	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，然后重启。

客户端无法找到 npx（spawn ENOENT）

从 Dock 或开始菜单启动的 GUI 客户端（Claude Desktop、Cursor、VS Code，……）会继承一个精简的 PATH，可能无法找到安装在 /opt/homebrew/bin、~/.nvm/...、mise 或 volta 下的 Node 工具。这会影响所有基于 npx 的 MCP，而不仅是此服务。错误会显示在 MCP 客户端日志中：

Connection failed: spawn npx ENOENT

选择一种修复方法：

1. 将 npx / node 符号链接到 GUI 可见的路径（macOS、Homebrew）：

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

2. 在 MCP 配置中使用绝对路径——可移植性最佳，不依赖 PATH。使用 which node 和 npm root -g 获取路径：

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

   需要一次性运行 npm install -g hana-mcp-server。

3. 在 MCP 的 env 块中注入 PATH——保留 npx 的写法：

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

更改后重启 MCP 客户端。如果随后 npx 因 ~/.npm/_cacache 上的 EPERM 而失败，说明 npm 缓存中有先前通过 sudo npm 创建的 root 所有文件——运行 sudo chown -R "$(whoami)" ~/.npm 修复，或在同一个 env 块中设置 "NPM_CONFIG_CACHE": "/tmp/hana-mcp-npm-cache"。

---

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

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.