HANA Cloud MCP Server

SAP HANA MCP Server

SAP HANA MCP Server は、SAP HANA および SAP HANA Cloud 向けに Model Context Protocol を実装しています。AI クライアントはスキーマを検出し、ガードレールを適用して SQL を実行できます。また、必要に応じて ビジネス／ドメインメタデータ を統合し、データベースを信頼できる唯一の情報源として維持したまま、エージェントがコードやテーブルを一貫して解釈できるようにします。

---

📚 ドキュメント

ドキュメント	目的
この 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	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 を省略できます。

3. Claude Desktop を再起動します。

任意： HANA MCP UI — npx hana-mcp-ui を使って env を編集し、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

Cursor／HTTP 経由のローカル IDE： start:http を実行するシェル（またはプロセスマネージャー）で HANA_* を設定し、url が http://127.0.0.1:3100/mcp の HTTP MCP エントリを追加します（Cursor のバージョンに応じて "type": "fetch" または "type": "http"）。docs/local-http-mcp.md と ./scripts/start-http-mcp.sh を参照してください。

トピック	詳細
エンドポイント	/mcp への POST JSON-RPC（デフォルトのベース URL は 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。

---

🎯 機能

34 個のツールを 6 つの領域にわたって提供しており、すべて 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／CHECK 制約、インデックス、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	行数、サンプル行、個別値数／NULL の統計、クエリ実行計画、オブジェクトの依存関係グラフ、パーティション情報、コストの高い上位のステートメント
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	stderr の出力を減らすため、stdio では false にすることがよくあります

*コード上のデフォルト値です。例ではファイルロギングを true に設定していることがよくあります。

制限（クエリ、リスト、リソース）

パラメーター	デフォルト	用途
HANA_QUERY_LIMITS_ENABLED	false	自動的な行数／列数／セル数の上限を有効にするには、true に設定します。false の場合でも、ユーザーが指定した maxRows、offset、includeTotal は引き続き使用できます。
HANA_QUERY_TIMEOUT_MS	0	ステートメントのタイムアウト（ミリ秒）。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_DATABASE_NAME は接続先のテナント（例：HQP）のままにして、HANA が想定する 3 部構成の名前（例：HSP.SAPABAP1.TABLE）を使用してください

デバッグ： 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 つ選んでください。

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 エラーになる場合は、以前の sudo npm によって 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.