Claude CodeでSAP HANA CLIのMCPを使う — 登録と権限の設計

SAP HANAのデータベースを触る作業を、Claude Codeから自然言語で頼めるようにするのがhana-cliのMCPサーバーです。hana-cliはSAPのサンプルプロジェクトとして公開されているNode.js製のコマンドラインツールで、テーブル一覧、データのインポートとエクスポート、性能調査などの操作をひとまとめにしています。MCPサーバーはそのコマンドをツールとして公開します。

この記事では、Claude Codeへの登録方法を3通り比べ、接続情報の置き方、動作確認、そして書き込み系のツールを勝手に走らせない権限設定までを順に書きます。

hana-cliのMCPサーバーは何を公開するのか

hana-cliのMCPサーバーは、hana-cliの全コマンドをMCPツールとして外に出す仕組みです。ただし最初から全部を並べません。起動直後に登録されるのは約22個で、必要になった分だけ増やす段階公開の設計です。

層	主なツール	役割
常時	主なツール`hana_query_simple` / `hana_tables` / `hana_inspect_table` / `hana_views` / `hana_status`	役割接続確認、一覧、構造の確認、SQL実行
ルーター	主なツール`hana_execute`	役割上記以外のコマンドを名前で呼び出す
発見系	主なツール`hana_recommend` / `hana_search` / `hana_discover_by_category` ほか	役割目的に合うコマンドを探す
内容系	主なツール`hana_examples` / `hana_parameter_presets` / `hana_get_doc` ほか	役割使用例とドキュメントを返す
動的	主なツール最大50個	役割カテゴリを探索したときに追加される

総数の書き方はページによって違います。MCP統合ガイドは全186コマンド、Claude Code用プラグインのREADMEは166ツールとしています。数が一致しないので、手元で使えるツールは/mcpの画面で数えるのが確実です。

登録方法は3つ。どれを選ぶか

登録の入口は複数あります。Claude Codeで使うなら次の3つが現実的です。

方法	コマンド	向く場面
`claude mcp add`	コマンド`claude mcp add --transport stdio hana-cli -- npx -y -p hana-cli hana-cli-mcp`	向く場面まず試す。hana-cliのインストール不要
プラグイン	コマンド`/plugin install https://github.com/SAP-samples/hana-cli-claude-plugin`	向く場面配布形態に乗せたい
hana-cli自身	コマンド`hana-cli mcp --client claude-code`	向く場面hana-cliを導入済みで設定ファイルを自動で書かせたい

npxで登録する(最短)

Claude Codeのドキュメントにある標準形は、--の前にClaude側のオプション、後ろにサーバーを起動するコマンドを置く書き方です。-p hana-cliの-pは--より後ろなので、Claude Codeではなくnpxに渡ります。

claude mcp add --transport stdio hana-cli -- \
  npx -y -p hana-cli hana-cli-mcp
claude mcp get hana-cli

claude mcp addはスコープを指定しない場合、ローカルスコープ(自分だけ・そのプロジェクトだけ)に書き込みます。チームで共有するなら--scope projectを付けると、プロジェクト直下の.mcp.jsonに入ります。共有した.mcp.jsonのサーバーは、各メンバーがclaudeを開いて承認するまでPending approvalのままです。

JSONで直接書くなら、.mcp.jsonに次の形です(hana-cliのドキュメントにある例)。

{
  "mcpServers": {
    "hana-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "hana-cli", "hana-cli-mcp"]
    }
  }
}

hana-cli mcpで設定を書かせる

hana-cliを入れているなら、設定ファイルへの書き込みを任せる手もあります。

hana-cli mcp --dry-run
hana-cli mcp --client claude-code
hana-cli mcp-status

先に--dry-runで書き込み内容を見ます。--clientを省略した自動検出では、すでに存在する設定ファイルにしか書きません。ドキュメントによると、この方法はMCPサーバーのビルド済みが前提です。ソースを取得した場合はmcp-serverでnpm installとnpm run buildが要ります。

注意点が1つあります。--globalの説明文には書き込み先が~/.claude/settings.jsonとある一方、同じページの対応表は~/.claude.jsonです。Claude Codeはsettings.jsonのmcpServersを読まないので、実行後はclaude mcp listにhana-cliが出ているかを必ず確かめてください。

プラグイン経由の場合

プラグインで入れると、ツール名の形が変わります。Claude Codeのドキュメントでは、プラグイン同梱のMCPサーバーのツール名はmcp__plugin_<プラグイン名>_<サーバー名>__<ツール名>です。次の章の権限ルールは、この名前に合わせて書き換えます。実際の名前は/mcpでツールを選ぶと見えます。

接続情報は登録より先に用意する

MCPサーバーを登録しても、HANAへの接続情報が無ければツールは何も返せません。hana-cliは次の順で接続設定を探します。

管理者モードならdefault-env-admin.json
.cdsrc-private.json(CAPのcds bindで資格情報を動的に取得)
.envのVCAP_SERVICES
--connで指定したファイル
カレントか親ディレクトリ5階層以内のdefault-env.json
~/.hana-cli/default.json

BTPのHANA Cloudなら、サービスキーからdefault-env.jsonを作れます。対話式の設定もあります。

hana-cli serviceKey -i <インスタンス名> -k <キー名>
hana-cli connect
hana-cli status

default-env.jsonにはパスワードが平文で入ります。READMEは、.cdsrc-private.jsonを使う方法を最も安全な選択肢としています。資格情報をローカルに置かず、実行のたびにCloud FoundryやKubernetesから取る方式です。代わりにコマンドごとに数秒余計にかかります。

複数プロジェクトを行き来するなら、各ツールが受け取る__projectContextパラメーターでprojectPathとconnectionFileを指定する方法もあります。

動作確認と最初の依頼

登録後は3段階で確かめます。

シェルでclaude mcp get hana-cliを実行し、接続状態を見る
Claude Code内で/mcpを開き、hana-cliのツール一覧を見る
「hana_statusで接続を確認して」と頼み、接続先ホストとユーザーが返るか見る

3で接続できたら、読み取りの依頼から始めます。

HRスキーマのテーブルを一覧にして、ORDERSの列定義を見せて。
更新は一切しないで。

この依頼にはhana_tablesとhana_inspect_tableが対応します。複雑な依頼のために、hana_recommendで目的に合うコマンドを探す入口も用意されています。たとえば「顧客テーブルの重複行を探したい」と伝えると、候補のコマンドと確信度、パラメーターのひな形を返すとドキュメントは説明しています。

引数が分からないコマンドは使用例から引く

ルーター越しのコマンドは引数の名前が分かりにくいものです。hana_examplesにコマンド名を渡すと複数の使用例が返り、hana_parameter_presetsは用途別の引数の組み合わせを返します。たとえばデータ品質を調べるdataProfileには、data_qualityという用途のプリセットがドキュメントに載っています。引数を推測で組ませる前に、この2つを先に引かせると呼び出しの失敗が減ります。

22個から186コマンドへ — ルーターと動的昇格の仕組み

常時登録のツールに無い操作は、2つの経路で使えます。

ルーター: hana_executeにコマンド名と引数を渡す。dataProfile、import、compareSchemaなどが対象
動的昇格: hana_discover_by_categoryでカテゴリを調べると、そのカテゴリのツールが直接呼べるツールになる

動的昇格が起きるとサーバーはtools/list_changed通知を送り、クライアントがツール一覧を更新します。昇格できるのは最大50個で、超えると古いカテゴリから外れます。

全部を最初から出したいなら、起動引数に--fullを足します。

{
  "mcpServers": {
    "hana-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "hana-cli", "hana-cli-mcp", "--full"]
    }
  }
}

Claude Codeにはツール検索の仕組みがあり、MCPツールが多くても毎回すべてをコンテキストに載せません。既定の約22個から始め、ルーター越しの呼び出しが手間になったときに--fullを試す順で足ります。全ツールを出す場合、Claude Codeはフルネームが128文字を超えるMCPツールを送信対象から外します。/mcpで出ないツールがあれば、ツール名の長さ上限の記事の確認手順が使えます。

権限設計 — 読む、書く、消すを分ける

ルーターのhana_executeは、名前を指定すれば任意のhana-cliコマンドを呼べます。インポートも、バックアップの操作も、HDIコンテナの操作もその経路です。許可ルールを雑に書くと、読み取りのつもりで書き込みまで通ります。

Claude Codeの許可ルールはmcp__<サーバー名>__<ツール名>の形です。許可側のワイルドカードはmcp__<サーバー名>__というリテラルの接頭辞の後ろにしか使えません。そこで、読み取り中心の常時ツールだけを個別に許可し、hana_executeとhana_query_simpleは都度確認にします。

{
  "permissions": {
    "allow": [
      "mcp__hana-cli__hana_status",
      "mcp__hana-cli__hana_tables",
      "mcp__hana-cli__hana_views",
      "mcp__hana-cli__hana_inspect_table"
    ],
    "deny": [
      "Read(./default-env.json)",
      "Read(./default-env-admin.json)"
    ]
  }
}

この設定の意図は次のとおりです。

構造を見るだけの4ツールは確認なしで通す
hana_query_simpleは「SQLを実行する」と説明されているだけで、SELECT以外を拒否するかはページに記載がない。許可に入れない
hana_executeは書き込み系のコマンドも通る経路なので許可に入れない
資格情報ファイルはReadの拒否ルールでClaudeのファイルツールから隠す(MCPサーバーは別プロセスなので、接続には影響しない)

プラグインで入れた場合は、先に述べたプラグイン用のフルネームに置き換えてください。

最後の砦はデータベース側です。権限ルールはClaude Codeの内側の話で、HANAのユーザーに書き込み権限があれば、承認ボタンを押した時点で書き込みは通ります。調査用には、SELECT権限だけを持つ専用ユーザーのdefault-env.jsonを用意するのが堅実です。権限の付け方はHANA側の設計で決まります。書き込み系のコマンドが失敗する構成にしておけば、承認を誤っても被害が止まります。

データのインポートは「dryRunを先に」をCLAUDE.mdに書く

書き込みを頼むときの手順も、hana-cliのドキュメントにあります。safe-importというワークフローは5段階です。

手順

safe-importの流れ

1
dry run
dryRun: trueでインポートを試走する。
2
エラーを確認
試走の出力から取り込めない行を洗い出す。
3
検証
データの検証コマンドで制約違反を確かめる。
4
インポート
dryRunを外して本番実行する。
5
結果の確認
件数と内容を確認する。

ワークフローを一覧するのはhana_workflows、個別の手順を取るのはhana_workflow_by_idです。ただしドキュメントによると、手順を実行するのはAIエージェントで、テンプレートは順序と推奨パラメーターを示すだけです。順番を飛ばさせないために、Claude Code側にも規約を置きます。

# HANA操作の規約(CLAUDE.md)
- HANAの操作はhana-cliのMCPツールで行い、hdbsqlを直接叩かない
- 書き込みを伴うインポートは、必ず`dryRun: true`を先に実行して結果を報告する
- 報告を受けてから本実行に進み、実行後に件数を確認する
- 接続先がdefault-env.jsonのどれかを最初に`hana_status`で表示する
- default-env-admin.jsonは読まない

「接続先をまず表示させる」ルールは、開発用と本番用の接続を取り違えるミスへの保険になります。

つまずきと対処

症状	原因の候補	対処
`claude mcp list`に出ない	原因の候補`hana-cli mcp`の書き込み先がClaude Codeの読む場所と違う	対処`claude mcp add`で入れ直す
ツールが0個	原因の候補ビルド失敗、依存関係の不足(ソースから入れた場合)	対処`mcp-server`で`npm install`と`npm run build`を再実行
接続エラー	原因の候補`default-env.json`が見つからない、ホスト・認証の誤り	対処`hana-cli status`をシェルで直接実行して切り分ける
一覧が空	原因の候補スキーマ指定やユーザーの権限	対処ドキュメントの「Zero Results from List Commands」の手順を確認
実行がタイムアウト	原因の候補クエリが重い、ネットワーク遅延	対処`--timeout`を延ばす、`--schema`や`--table`で絞る
件数が表示と違う	原因の候補ページごとに総数の書き方が違う	対処`/mcp`で実際の個数を数える

Node.jsの要件もページで食い違います。メインのREADMEとMCP設定の章は22以上、プラグインのREADMEは20.19.0以上、トラブルシューティングは14以上と書いています。メインのREADMEは「24 LTS推奨」とも書いているので、迷うなら22以上、できれば24で揃えてください。

まとめ

登録そのものはclaude mcp addの1行で終わります。作業の中心は、接続情報を平文で置かない構成を選ぶことと、hana_executeを許可に入れない権限設計の2つです。まずは読み取り専用ユーザーでhana_statusから始め、書き込みはdryRunを挟む規約をCLAUDE.mdに置いてから任せる流れが、事故の幅を小さく保てます。

SAP開発の周辺では、CDSモデルを検索するcds-mcpの記事や、UI側を担うUI5 MCPサーバーの記事も同じMCPの仕組みで動きます。

Claude CodeでSAP HANA CLIのMCPを使う — 登録と権限の設計

hana-cliのMCPサーバーは何を公開するのか

登録方法は3つ。どれを選ぶか

npxで登録する(最短)

hana-cli mcpで設定を書かせる

プラグイン経由の場合

接続情報は登録より先に用意する

動作確認と最初の依頼

引数が分からないコマンドは使用例から引く

22個から186コマンドへ — ルーターと動的昇格の仕組み

権限設計 — 読む、書く、消すを分ける

データのインポートは「dryRunを先に」をCLAUDE.mdに書く

つまずきと対処

まとめ

Claude Codeとは — できること・料金・始め方と使い方の全体像

Claude CodeのAppwriteプラグインでFunctionsとSitesをデプロイする

IPGeolocation.io MCPをClaude Codeにつないで不審なIPを調べる手順

ClaudeでSumo Logic MCPを使う方法 — ログ検索とアラート確認を権限つきで任せる

ClaudeにMLflow MCPを繋いでトレース調査と評価ループを回す

Claude CodeにMapbox MCPを入れて地図・ルート検索を作る

hana-cliのMCPサーバーは何を公開するのか

登録方法は3つ。どれを選ぶか

npxで登録する(最短)

hana-cli mcpで設定を書かせる

プラグイン経由の場合

接続情報は登録より先に用意する

動作確認と最初の依頼

引数が分からないコマンドは使用例から引く

22個から186コマンドへ — ルーターと動的昇格の仕組み

権限設計 — 読む、書く、消すを分ける

データのインポートは「dryRunを先に」をCLAUDE.mdに書く

つまずきと対処

まとめ

関連する記事

Claude Codeとは — できること・料金・始め方と使い方の全体像

Claude CodeのAppwriteプラグインでFunctionsとSitesをデプロイする

IPGeolocation.io MCPをClaude Codeにつないで不審なIPを調べる手順

ClaudeでSumo Logic MCPを使う方法 — ログ検索とアラート確認を権限つきで任せる

ClaudeにMLflow MCPを繋いでトレース調査と評価ループを回す

Claude CodeにMapbox MCPを入れて地図・ルート検索を作る