HANA Cloud MCP Server
SAP HANA MCP 服务器
SAP HANA MCP 服务器 为 SAP HANA 和 SAP HANA Cloud 实现了 模型上下文协议 (Model Context Protocol)。AI 客户端可以发现模式、在防护机制下运行 SQL,并可选择合并 业务/领域元数据,以便代理能够一致地解释代码和表——而无需替换您作为记录系统的数据库。
📚 文档
文档 | 用途 |
本 README | 先决条件、安装、如何连接各客户端、功能摘要、配置速查表、故障排除 |
发布历史 — 按版本划分的功能和修复 ( | |
| |
权威环境变量参考:每个变量、默认值、硬性限制、HTTP 认证、安全说明 | |
复制粘贴:连接配置文件(单容器、MDC)、语义 JSON、分页指针 | |
本地 HTTP MCP: |
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 配置中的 | 默认 — 无需全局安装 |
| 您需要在 |
克隆 + | 开发或固定本地构建版本 |
HTTP 入口点 (从克隆版本):npm run start:http — 默认绑定 127.0.0.1:3100,路径 /mcp。参见 托管与 HTTP。
🎯 使用场景
受众 | 传输方式 | 下一步 |
聊天 / 轻量用户 | stdio | |
开发人员 (Claude Code, VS Code, Cline, Cursor, Windsurf) | stdio | |
带有 AI 代理的业务应用 (您通过 HTTP 托管 MCP) | HTTP |
🖥️ Claude Desktop
配置文件路径:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\claude\claude_desktop_config.jsonLinux:
~/.config/claude/claude_desktop_config.json
注册服务器;将连接设置放入
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。
重启 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。
主题 | 详情 |
端点 |
|
调优 |
|
健康检查 |
|
CORS |
|
可选 Bearer JWT (OAuth2 / OIDC)
变量 | 角色 |
|
|
| 颁发者 / JWKS (在绑定了 XSUAA 的 SAP BTP 上省略) |
| 可选的预期 |
| 可选的作用域列表 |
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 的行数、列数和单元格大小的限制;在支持的情况下通过 |
资源 | 用于列表/读取的 |
领域知识 (可选) | 用于 |
🛠️ 配置
变量适用于 stdio (客户端配置中的 env) 和 HTTP (进程环境变量)。更改后请重启。
名称、默认值和限制范围的权威来源: docs/ENVIRONMENT.md。 复制粘贴连接 JSON (单容器 / MDC): docs/configuration-samples.md#connection-profiles-env-json。
必需
参数 | 描述 | 示例 |
| 主机名或 IP |
|
| 数据库用户 |
|
| 数据库密码 | (密钥) |
连接与 TLS
参数 | 默认值 | 说明 |
|
| MDC SQL 端口通常为 |
| — | 工具省略 |
|
|
|
| — | MDC 实例 ID (例如 |
| — | MDC 的 租户 名称 (例如 |
|
| 驱动程序的 TLS 和证书验证标志 |
日志记录
参数 | 默认值 | 说明 |
|
|
|
|
|
|
|
| 对于 stdio,通常设为 |
*代码默认值;示例通常将文件日志记录设置为 true。
限制 (查询、列表、资源)
参数 | 默认值 | 用途 |
|
| 每个 |
|
| 每行返回的最大列数 |
|
| 截断过长的单元格文本 |
|
| 默认 |
|
| 列表工具:默认和最大页面大小 |
|
|
|
|
| 查询分页的快照 ID 生命周期 |
业务 / 领域 JSON (HANA_SEMANTICS_*)
参数 | 默认值 | 用途 |
| — | 字典 JSON 的文件路径 (优先级高于 URL) |
| — | 相同格式的 HTTPS URL |
|
| 缓存 / 重新加载行为 |
🔧 故障排除
症状 | 检查 |
连接被拒绝 |
|
认证失败 / 无客户端 | 密码、用户、租户上的 |
TLS 错误 |
|
对象错误或为空 | MDC:租户决定可见性;相同的模式名称在不同租户下可能不同 |
SQL 需要另一个数据库前缀 |
|
调试: LOG_LEVEL=debug, ENABLE_CONSOLE_LOGGING=true, 重启。
🖥️ HANA MCP UI
npx hana-mcp-ui
🏗️ 架构
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 |
依赖 |
|
🤝 支持
问题: GitHub Issues
UI: HANA MCP UI
📄 许可证
MIT — 参见 LICENSE。
Available Tools
9 toolshana_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Remote data science agents for Snowflake, Databricks & BigQuery in Claude/Cursor via MCP
A Model Context Protocol server for Wix AI tools
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to explore and interact with Cursor IDE's SQLite databases, providing access to project data, chat history, and composer information.26-
- AlicenseNot gradedqualityDmaintenanceExposes 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
- AlicenseAqualityDmaintenanceEnables AI assistants to query, analyze, and manage SQL Server databases through natural language via the Model Context Protocol.61MIT
- AlicenseNot gradedqualityDmaintenanceA 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