mcp-sap-gui

MCP SAP GUI サーバー

SAP GUI Scripting API を通じて、AI アシスタントが Windows 用 SAP GUI とやり取りできるようにする MCP（Model Context Protocol） サーバーです。

クライアントに依存しません。MCP クライアントからローカルの stdio サーバーを起動できれば、このプロジェクトを利用できます。この README ではセットアップを簡単に説明するため Claude を例にしていますが、同じサーバーを Codex、GitHub Copilot、Gemini CLI など、MCP に対応したツールから利用できます。

現在のリリース：MCP stdio を介したローカル Windows 用の 0.5.4。

ステータス

• CI、Docs、Dependency Audit、タグベースのRelease向けに GitHub ワークフローを用意しています。
• 主要リポジトリ：GitHub（kts982/mcp-sap-gui）。

新機能

0.5.4 は HTTP トランスポート向けのセキュリティリリースです。DNS リバインディングを利用して Web ページから偽装できるリクエストを拒否するようになりました（アドバイザリ）。デフォルトの stdio は影響を受けません。また、sap_set_policy_profile の制限が1日後に失効しないようになり、サーバー自身のバージョンも報告するようになりました。リリースごとのすべての変更については、CHANGELOGをご覧ください。

sap_preview — 実行前に確認できます。 エージェントは、バッチ書き込みの前、保存の前、またはリクエストされたとき（「国 GR を追加する前に、値を見せてください」）など、任意のチェックポイントで承認カードを表示できるようになりました。現在のスクリーンショット、セッションのコンテキスト、これから書き込む正確な値が含まれます。パスワード形式の値はマスキングされます。MCP Apps ホスト（VS Code Copilot Chat）ではリッチなインラインカードとして表示され、それ以外では同じ概要がテキストとスクリーンショットで表示されます。保存には引き続き確認ゲートが適用されます。詳細：プレビューカードの表示。

確認ポイント — 承認なしに書き込みは行われません。 エージェントに一度指示するだけで（「各フィールドへの書き込み前に確認してください」）、サーバーがそれを適用します。sap_set_confirmation_points により、書き込み操作のカテゴリを有効にすると、SAP に何かが送信される前に処理が一時停止し、明示的な承認を求めます。ミドルウェアによってサーバー側で適用されるため、エージェントの動作にかかわらず、拒否すると呼び出しはブロックされ、ゲートを削除する際には事前に確認が求められます。また、管理者は --confirm を指定して、すべてのセッションにゲートを固定できます。詳細：セキュリティに関する考慮事項。

このサーバーでできること

このサーバーにより、AI アシスタントは次の操作を行えます。

• SAP システムに接続する（SAP Logon Pad でダブルクリックするのと同様）
• トランザクションを実行する（MM03、VA01、/SCWM/MON など）
• 画面のフィールド、チェックボックス、ラジオボタン、コンボボックス、タブの読み取りと書き込み
• F4 値ヘルプを使用する：ヒットリスト、制限ダイアログ、日付および時刻ピッカー
• メニューバーからメニュー項目を選択する（テーブルビュー、編集、選択など）
• キー入力やボタンを使って SAP 画面を移動する
• ALV グリッド（GuiGridView）および従来型のテーブルコントロール（GuiTableControl）からデータを抽出する
• 従来型のレポートリスト（WRITE 出力）を、行の色も含めてテキストとして読み取る
• ALV ツールバーのボタンやコンテキストメニューを操作する
• ビュークラスタのドッキングダイアログ構造を含め、ツリーコントロール（TableTree、ColumnTree、SimpleTree）を読み取り、操作する
• SAP ウィンドウのスクリーンショットをインラインで取得するか、フル解像度のファイルとして保存する
• 自動化のために画面要素を検出する
• 書き込み前にプレビューを表示し、選択した確認ポイントで承認を求めて処理を一時停止する

会話の例

User: "What's the description for material MAT-001 in system D01?"

Assistant: [connects to D01]
           [executes MM03]
           [enters material number]
           [reads description field]

"The material MAT-001 is described as 'High-Grade Steel Plate 10mm'
in system D01."

クイックスタート

1. まだインストールしていない場合は、uv をインストールします（uvx が同梱されています）。

pip install uv

2. SAP Logon Pad を起動して SAP GUI セッションを開くか、少なくとも SAP Logon を実行しておきます。

3. このサーバーを起動するように MCP クライアントを設定します。クローンや手動インストールは不要です。uvx が PyPI のリリース済みパッケージを取得し、隔離された環境で実行します。

Command:   uvx
Arguments: mcp-sap-gui[screenshots]
Transport: stdio

ソースをチェックアウトして作業する場合は、インストールを参照してください。

4. 次のプロンプトのいずれかを試してください。

Connect to my open SAP session and tell me what system I'm on
Show me the current screen info
List all editable fields on this screen
Read the first 20 rows of the visible table

sap_connect は意図的にパスワードパラメーターを受け付けません。より安全な方法は、まず SAP GUI でログインし、その後 sap_connect_existing で接続することです。

要件

• Windows（SAP GUI は Windows でのみ実行されます）
• SAP GUI for Windows がインストールされていること
  • SAP GUI for Windows 8.10 64-bit Patch 0 で実環境での互換性を確認済みです。SAP は 8.10 を 2029 年 6 月 30 日まで、8.00 を 2027 年 1 月 12 日までサポートします（制限付きサポートは 2027 年 7 月 31 日まで）。7.70 以前は SAP のサポート対象外で、可能な範囲で動作します。日付、出典、各機能に必要なリリースについては、SAP GUI バージョンを参照してください。
  • 7.70 Patch Level 3 以降では、画面全体、ポップアップ、リストページ、またはテーブルコントロールを 1 回の呼び出しで読み取ります（GetObjectTree）。それ以前のリリースでは要素ごとに読み取るため、大きな画面では大幅に遅くなります（リストページ全体の読み取りに、1 秒未満ではなく数秒かかります）。
• SAP Logon Pad が実行中であること。または SAP Business Client（実験的機能。以下を参照）や別の埋め込み型 SAP GUI がホストする SAP GUI セッションがあること（COM 接続の場合）
• SAP システムで SAP GUI Scripting が有効になっていること
• Python 3.10+
• uv（推奨 Python パッケージマネージャー）

SAP Business Client（実験的機能）

• SAP Business Client の従来型トランザクションは埋め込み型 SAP GUI for Windows で実行されるため、サーバー側のスクリプトパラメーターが引き続き必要です。sapgui/nwbc_scripting を使うと、読み取り専用のスクリプト機能が有効になります（sapgui/user_scripting と sapgui/user_scripting_set_readonly を組み合わせた場合と同じ効果です）。書き込みツールは拒否され、グリッドをスクロールできないため、テーブルの読み取りは画面上の行で止まります。
• セッションは、SAP GUI サーバープロセスの COM Running Object Table エントリー（SAPGUISERVER-<pid>）から検出されます。これは通常の SAP Logon エントリーと並んでいます。該当するセッションについて、sap_list_connections は host: "sapguiserver" を返します。
• 1 つの Business Client ウィンドウ内のタブは同じ接続のセッションです。2 つ目のシステムは別の接続になります。
• Business Client 接続には SAP Logon の説明がありません。リストには代わりにシステムとクライアントが表示されます（例：DEV (100)）。
• Back を繰り返し押すと、SAP Easy Access メニューに戻らずにタブが閉じます（SAP Business Client FAQ）。
• Fiori Launchpad の接続では、トランザクションが SAP GUI for HTML として表示される場合があります。このようなトランザクションはスクリプトから認識できません。

サポート対象の範囲

サポート対象：

• SAP GUI Scripting COM API を使用した SAP GUI for Windows
• MCP の stdio（デフォルト）および streamable HTTP トランスポート
• クライアントごとのセッション分離（複数の MCP クライアントが独立した SAP セッションを保持できます）
• MCP 対応クライアントからの対話的な使用
• ログイン中の SAP ユーザーの権限内での SAP GUI の読み取りおよび書き込み自動化

未対応：

• SAP GUI for Java または SAP GUI for HTML
• ブラウザーを使用した Fiori の自動化
• 無人のマルチユーザー本番環境オーケストレーション

SAP GUI Scripting の有効化

SAP GUI Scripting はクライアント側とサーバー側の両方で有効にする必要があります。

クライアント側（SAP GUI オプション）：

1. SAP GUI → Options → Accessibility & Scripting → Scripting を開きます
2. 「Enable scripting」にチェックを入れます
3. 必要に応じて、よりスムーズに自動化するため「Notify when a script...」のチェックを外します

サーバー側（SAP システム）：

• トランザクション RZ11 → パラメーター sapgui/user_scripting → TRUE に設定します
• SAP Basis 管理者のアクセス権が必要です

スクリプト実行が制限されている環境へのデプロイ

多くの組織では、セキュリティ強化のためのデフォルト設定として、SAP GUI Scripting を全体で無効にしています。有効化は、すべてを許可するか、すべてを禁止するかの二択ではありません。SAP には段階的なサーバー側制御が用意されており、Basis チームは、通常は開発システム上の指定ユーザーに限ってスクリプトを有効にし、それ以外のユーザーには無効のままにできます。

プロファイルパラメーター（RZ11／RZ10）	効果
sapgui/user_scripting = TRUE	マスタースイッチです。あらゆるスクリプト実行に必須です
sapgui/user_scripting_per_user = TRUE	権限オブジェクト S_SCR（クラス BC_A、アクティビティ 16）を持つユーザーのみスクリプトを実行できます。それ以外のユーザーは引き続きブロックされます（SAP Note 983990）
sapgui/user_scripting_set_readonly = TRUE	スクリプトは画面の状態を読み取れますが、サーバーの状態を変更する操作は送信できません（SAP Note 692245）
sapgui/user_scripting_force_notification = TRUE	スクリプトが接続するたびに、ユーザーに通知／同意ダイアログが必ず表示されます。ローカルの SAP GUI オプションでは抑止できません（SAP Note 3591984）
sapgui/user_scripting_disable_recording = TRUE	新しいスクリプトの記録をブロックします。再生は引き続き可能です

Basis／セキュリティチームに提案する際に役立つ情報：

• ユーザーごとのモードと読み取り専用モードは、SAP GUI 7.40 PL17／7.50 PL4 以降、併用できます。S_SCR を持つユーザーには完全な API を、それ以外のユーザーには読み取り専用の API を提供できます（SAP Note 2565390）。
• 読み取り専用セッションでは、このサーバーはセッション情報に scripting_read_only: true を報告し、書き込みツールを実行前に理由とともに拒否します。そのため、各操作が SAP GUI 内で失敗することはありません。読み取りツールはすべて引き続き動作します。
• RZ11 で sapgui/user_scripting を動的に変更しても永続化されません。次回のアプリケーションサーバー再起動時に元に戻るため、開発システムで期間を限定して評価する用途に適しています。
• サーバー側では、スクリプトによる操作は SAP ユーザーの通常の権限で実行され、通常のユーザー操作としてログに記録されます。実効的なセキュリティ境界となるのはユーザーの権限プロファイルです。多層防御のため、最小限の権限を持つ専用アカウントを、このサーバーのトランザクションポリシー（--policy-preset、--policy-file）、--profile、--audit-log オプションと組み合わせてください。
• 信頼できる参照資料：SAP GUI Scripting Security Guide（help.sap.com）。

Scripting API が必要な理由： SAP GUI for Windows は、Windows UI Automation やその他のアクセシビリティ API では利用可能な構造を取得できないカスタムキャンバス上に dynpro 画面を描画します。SAP GUI の画面を構造化された方法で読み取り、操作する唯一の手段が Scripting API です。商用の RPA 製品も同じ依存関係があり、スクリプトが無効な場合はスクリーンショット／OCR ベースの自動化に切り替えます。このプロジェクトでは、精度が低く不安定なため、その方法を意図的に避けています。

インストール

PyPI からインストール（ユーザーに推奨）

クローンは不要です。初回起動時に uvx が最新リリースをダウンロードし、隔離された環境で実行します。

# Smoke test the published package
uvx "mcp-sap-gui[screenshots]" --help

[screenshots] エクストラを指定すると、スクリーンショットの最適化が追加されます（サイズを 70～90％削減）。追加することをおすすめします。Python 3.11 以降が必要です。3.10 では何もインストールされず、スクリーンショットは最適化されません。MCP クライアントの起動先を uvx に設定し、引数に mcp-sap-gui[screenshots] を指定してください。詳しくは、以下のMCP のセットアップを参照してください。

新しいリリースへの更新： 初回起動後、uvx はキャッシュしたバージョンを再利用するため、新しいリリースは自動では適用されません。uvx "mcp-sap-gui[screenshots]@latest" --help を一度実行してから、MCP クライアントを再起動してください。次回の起動時に新しいリリースが使用されます。特定のリリースを使い続けるには、クライアントの引数にバージョンを指定します：mcp-sap-gui[screenshots]==<version>。

ソースから実行する場合（開発用）

# Clone the repository
git clone https://github.com/kts982/mcp-sap-gui.git
cd mcp-sap-gui

# Install uv (if not already installed)
pip install uv

# Install all dependencies (creates .venv automatically)
uv sync

# With screenshot optimization (recommended - reduces screenshot size by 70-90%)
uv sync --extra screenshots

# With dev dependencies (for testing, linting, type checking)
uv sync --extra dev --extra screenshots

ソースチェックアウトを使用する場合の Windows に関する注意： このチェックアウトから起動した MCP サーバーの実行中は、そのプロセスが .venv 内のネイティブ DLL（pywin32、watchfiles）をロックします。その間に uv sync を実行したり、依存関係をアップグレードしたりすると、「Access is denied」エラーが発生したり、.venv が不完全な状態になったりする場合があります。まず MCP クライアントを停止または再起動してから、同期してください。2 つの MCP クライアント（例：Claude Code と VS Code）で同じチェックアウトからサーバーを起動する場合は、2 つ目のクライアントでは共有の .venv ではなく、分離された環境を指定してください。

Command:   uv
Arguments: run --isolated --no-project --with "mcp-sap-gui[screenshots,apps] @ file:///<path-to-checkout>" python -m mcp_sap_gui.server

（uvx mcp-sap-gui を使用する場合は影響ありません。uvx を起動するたびに、独自のキャッシュ環境が使用されます。）

使い方

接続に関する推奨事項：認証済みのセッションがすでにある場合は、sap_connect_existing を優先してください。sap_connect は主に、SSO フローの場合や、ユーザーが手動でログインする前に SAP のログイン画面を開く場合に使用してください。

MCP サーバーを直接実行する

# Standard mode (stdio, default)
uv run python -m mcp_sap_gui.server

# Read-only mode (safer for exploration)
uv run python -m mcp_sap_gui.server --read-only

# With transaction whitelist
uv run python -m mcp_sap_gui.server --allowed-transactions MM03 VA03 ME23N

# HTTP transport (binds to 127.0.0.1). Requests addressed to another host
# name (DNS rebinding) or sent by a web page from another origin are refused.
uv run python -m mcp_sap_gui.server --transport http

# HTTP on another address: name the host clients use for this machine
# (--allowed-origin adds a browser origin that may call the server)
uv run python -m mcp_sap_gui.server --transport http --host 0.0.0.0 --port 9000 --allowed-host sap-box

# Policy profile (restrict visible tools)
uv run python -m mcp_sap_gui.server --profile exploration

# Confirmation points (ask the user before these categories run, every session)
uv run python -m mcp_sap_gui.server --confirm field_writes transactions

# Audit log to file (JSON lines)
uv run python -m mcp_sap_gui.server --audit-log sap_audit.jsonl

# On shutdown, leave every SAP session open, even the ones sap_connect opened
uv run python -m mcp_sap_gui.server --detach-on-exit

# EXPERIMENTAL: code mode — replaces the tool catalog with search/get_schema/
# tags/execute meta-tools; agents script chained SAP flows in a sandbox.
# Faster and cheaper on long chained flows (e.g. full table dumps), slower on
# quick one-shot questions. Requires: uv sync --extra code-mode
uv run --extra code-mode python -m mcp_sap_gui.server --code-mode

# Same, from the published PyPI package (no checkout needed)
uvx "mcp-sap-gui[screenshots,code-mode]" --code-mode

# Debug mode
uv run python -m mcp_sap_gui.server --debug

MCP のセットアップ

このサーバーは、MCP の標準トランスポートである stdio（stdin/stdout JSON-RPC）を使用して通信します。ポートや URL の設定は不要です。MCP クライアントがサーバープロセスを起動し、直接通信します。

どのクライアントでも、基本的な起動設定は同じです。

Command:   uvx
Arguments: mcp-sap-gui[screenshots]
Transport: stdio

PyPI ではなくソースチェックアウトから実行しますか？コマンドとして uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server を使用してください。

クライアントのセットアップリンク

• Claude Code / Claude Desktop：セットアップ例は以下に記載されています
• Codex：Codex で MCP サーバーを設定し、上記のコマンドを指定してください。公式 MCP ドキュメント：https://developers.openai.com/learn/docs-mcp
• GitHub Copilot：Copilot Chat / エージェントモードでローカル MCP サーバーを設定してください。公式ドキュメント：https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp
• Gemini CLI：Gemini CLI の設定で、mcpServers の下にサーバーを追加してください。公式ドキュメント：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

以下に、一般的な SAP GUI のローカルセットアップ方法を詳しく説明します。

クライアントごとのセットアップガイドについては、docs/CLIENTS.md を参照してください。

---

オプション 1：Claude Code（開発に推奨）

リポジトリのプロジェクトルートには .mcp.json が含まれています。このプロジェクトを Claude Code で開くと、MCP サーバーが自動的に検出されるため、手動での設定は不要です。

使用するには、次の手順に従ってください。

cd mcp-sap-gui
claude

Claude Code は .mcp.json を検出し、SAP GUI MCP サーバーを自動的に起動します。

Claude Code でグローバルに設定して、どのプロジェクトからも使えるようにするには、ユーザー設定の ~/.claude/.mcp.json に追加してください。

{
  "mcpServers": {
    "sap-gui": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]"]
    }
  }
}

---

オプション 2：Claude Desktop

Claude Desktop の設定ファイルに追加してください。

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

標準モード：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]"]
    }
  }
}

注： PyPI ではなくソースチェックアウトから実行しますか？
"command": "uv" と "args": ["run", "--directory", "<path-to-mcp-sap-gui>", "python", "-m", "mcp_sap_gui.server"] を使用してください。Claude Desktop が使用する作業ディレクトリにかかわらず、uv がプロジェクトの仮想環境を見つけられるように、--directory フラグが必要です。

読み取り専用モード（データの参照・照会に推奨）：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]", "--read-only"]
    }
  }
}

トランザクション許可リストを指定する場合（特定のトランザクションのみ許可）：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": [
        "mcp-sap-gui[screenshots]",
        "--allowed-transactions", "MM03", "VA03", "ME23N"
      ]
    }
  }
}

設定を編集した後、変更を反映するために Claude Desktop を再起動してください。

---

オプション 3：MCP 対応クライアント全般

このサーバーは stdio トランスポートを使用します。任意の MCP クライアントで、次を指定してください。

Command:   uvx mcp-sap-gui[screenshots]
Arguments: [--read-only] [--profile exploration|operator|full] [--confirm POINT ...] [--audit-log FILE] [--detach-on-exit] [--debug] [--policy-preset default|abap-dev|strict] [--policy-file FILE] [--allowed-transactions T1 T2 ...]
Transport: stdio

ソースチェックアウトの場合は、代わりに uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server を使用してください。

---

セットアップの確認

設定が完了したら、Claude に質問して MCP サーバーが動作していることを確認できます。

"List all available SAP GUI tools"

Claude は sap_* ツールの全一覧を返すはずです。SAP GUI が実行中の場合は、次を試してください。

"Connect to my open SAP session and tell me what system I'm on"

続いて、次を試してください。

"Show me the current screen info"
"List all editable fields on this screen"
"Read the first 20 rows from the visible table"

組み込みエージェントガイダンス

このサーバーには、あらゆる MCP クライアント（Claude Code、Copilot、Cursor、Cline など）が SAP GUI を効果的に使用できるようにする、組み込みのナビゲーション知識が含まれています。

• MCP の指示 — 初期化時に、すべてのクライアントのシステムプロンプトに挿入されます。画面の検出ワークフロー、ポップアップの処理、テーブルのページネーション、SPRO ツリーのナビゲーション、キーのリファレンス、および避けるべきよくある間違いについて説明します。
• docs://sap-gui-guide リソース — resources/read を使って必要に応じて参照できる、詳細なリファレンスガイドです。要素の種類、ID の命名規則、トランザクションコードの形式、テーブルタイプの比較、ステータスバーのメッセージ、SPRO およびテーブル保守ビューの手順を説明します。

これにより、要素 ID を推測する、ポップアップを無視する、更新するつもりで F5（＝「新規エントリ」）を押す、SPRO で double_click_tree_node を使う（アクティビティを実行せず、ドキュメントを開きます）、ビュークラスターで double_click_tree_node を使う（何も起こりません）、またはクラシックレポートリストを sap_read_list ではなくスクリーンショットから読み取る、といったエージェントによくある間違いを防げます。

利用可能なツール

現在、このサーバーは 60 個の MCP ツールを公開しています。

カテゴリ	数	対応範囲
接続とポリシー	7	SAP への接続、開いているセッションへの接続、セッションの確認、切断、ポリシープロファイルの設定、確認ポイントの設定
ナビゲーション	3	トランザクションの実行、キーの送信、現在の画面の確認
フィールドと UI	13	フィールド、ボタン、タブ、コンボボックス、テキストエディター、フォーカスの読み取り／書き込み
テーブルとグリッド	17	ALV グリッド、TableControls、行の選択、列情報、セル操作
ポップアップ／ツールバー／シェル／リスト	5	ポップアップの確認と処理、ツールバーの検出、シェルの内容、クラシックレポートリスト
ツリー	10	SAP ツリーコントロールの読み取り／検索／展開／選択／クリック
検出	2	画面要素の検出とスクリーンショット
プレビュー	1	現在の画面と、エージェントがこれから書き込む値をユーザーに表示
ワークフローガイダンス	1	既知の複数ツールを使う SAP ワークフローについて、手順ごとのガイダンスを返す
トランザクションガイダンス	1	対応する SAP トランザクションについて、読み取り優先の汎用ガイドを返す

最も重要な使用パターンは次のとおりです。

• ID を推測せずに検出するには sap_get_screen_elements を使用します
• 任意の SAP テーブル／グリッドで作業を始めるには sap_read_table を使用します
• レポートが ALV グリッドではなく通常のリストを出力する場合は sap_read_list を使用します
• ポップアップが開くと、すべてのアクション応答に短い popup ダイジェスト（分類、テキスト、ボタンラベル、入力値やオプションがすでに設定されている場合の通知を含む prefilled_inputs）が含まれます。sap_get_popup_window では詳細をすべて確認でき、安全な次のステップの提案も表示されます
• 明らかに安全な情報ポップアップだけをサーバーに閉じさせ、それ以外のダイアログには手を加えない場合は sap_handle_popup(action="auto") を使用します
• 重要な書き込み操作（複数フィールドへの入力、F11 ／保存）の前に sap_preview を使うと、画面と保留中の値をユーザーに先に表示できます
• 書き込みカテゴリごとに、実行前にユーザーの承認を求めるには sap_set_confirmation_points を使用します
• 既知のワークフローで実証済みの手順を確認するには sap_get_workflow_guide を使用します
• 対応するトランザクションの汎用ガイドを確認するには sap_get_transaction_guide を使用します：/SCWM/MON（warehouse monitor も対象）、またはテーブル／ビューの保守やビュークラスターに対する SM30（SM34、view cluster も対象）
• SPRO 形式のナビゲーションには sap_read_tree と検索／展開ヘルパーを併用します

カテゴリ別に分類した簡単な説明付きの全ツールカタログは、docs/TOOLS.md を参照してください。

レンダリング済みプレビューカード

sap_preview は読み取り専用で、文章による要約とスクリーンショット画像を常に返すため、すべての MCP クライアントで動作します。MCP Apps UI 拡張機能をサポートするクライアント（VS Code Copilot など）では、代わりにスクリーンショットと保留中の値のテーブルを含むレンダリング済みカードが表示されます。カードを有効にするには、オプションの追加パッケージをインストールしてください。

uv sync --extra apps          # or: uvx "mcp-sap-gui[screenshots,apps]"

制限されたネットワーク、またはオフラインネットワークの場合： デフォルトではカードのレンダラーは jsDelivr CDN から読み込まれるため、外部インターネットにアクセスできないワークステーションではカードのレンダリングが失敗しても通知されません。レンダラーを自己完結型にするには、サーバーの環境で PREFAB_BUNDLED_RENDERER=1 を設定してください（約 6.3 MB のインラインリソースを使用し、サードパーティのドメインは不要です）。

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots,apps]"],
      "env": { "PREFAB_BUNDLED_RENDERER": "1" }
    }
  }
}

セキュリティに関する考慮事項

このサーバーは強力な自動化機能を提供します。責任を持って使用してください。

組み込みの保護機能

1. トランザクションポリシー - エージェントが開始できるトランザクションを指定します。何が危険かは、サーバーを実行するユーザーと対象システムによって異なるため、設定可能です。

   • --policy-preset default（デフォルト）では、ユーザーとロールの管理（SU01、SU10、SU01D、PFCG、SU53）、ログとダンプ（SM21、ST22）、開発とプログラムの実行（SE38、SA38、SE80、SE37、SE16N）、システム管理（STMS、SCC4、RZ10、RZ11、SM36、SM49、SM69、SM59、STRUST、SICF、SM01、SM18、SM19）をブロックします。カスタマイズと表示の作業（SM30、SM34、SPRO、SE16、SE11）は許可されます
   • --policy-preset abap-dev では、開発者が自分のプログラムをテストできるよう、SA38、SE11、SE80 も許可します
   • --policy-preset strict では、ポリシーファイルで許可されていないすべての操作をブロックします
   • --policy-file policy.json はプリセットにルールを追加します：{"preset": "abap-dev", "block": ["ZHR*"], "allow": ["SM59"]}。エントリにはコードまたは glob パターン（SU*、/SCWM/*）を指定できます。allow は常に block より優先されます。このフラグを指定しない場合、サーバーは $MCP_SAP_GUI_POLICY_FILE を読み込み、設定されていなければ、ファイルが存在する場合に %APPDATA%\mcp-sap-gui\policy.json を読み込みます。このファイルはエージェントのワークスペース外に保管してください
   • examples/ には 2 つの例が含まれています。policy.example.json は default をベースに、顧客名前空間（ZHR*）と SE16 を追加でブロックし、ダンプ分析用に ST22 を許可します。policy.strict.example.json は表示専用エージェント向けの許可リストです。Windows でいずれかをユーザーごとのポリシーとして設定するには、次を実行します：New-Item -ItemType Directory -Force "$env:APPDATA\mcp-sap-gui"; Copy-Item examples\policy.example.json "$env:APPDATA\mcp-sap-gui\policy.json"
   • ポリシーは起動時に一度だけ読み込まれ、ファイルの SHA-256 とともに監査ログに記録されます。どのツールからも変更できません。また、ポリシーファイルを読み込めない場合、より制限の緩い設定にフォールバックするのではなく、サーバーを停止します
   • 大文字と小文字を区別せずに照合し、/n、/o、/* のプレフィックスと空白に対応します
   • これはエージェントのミスを防ぐための安全策であり、セキュリティ境界ではありません。ブロックされたトランザクションに、メニュー経由や開いたままの画面経由でアクセスできる場合があります。境界となるのは SAP ユーザーの権限です

2. OK-Code による回避の防止 - tbar[0]/okcd、txtOK_CODE などの SAP コマンドフィールドや同様のコマンドコードの別名に、ブロック対象のトランザクションを設定する操作もブロックし、トランザクションポリシーの回避を防ぎます

3. 読み取り専用モード - --read-only フラグを指定すると、変更を伴うすべての操作（フィールドへの書き込み、ボタンの押下、トランザクションの実行、キーの送信、ツリーやテーブルの操作）が無効になります

4. トランザクションの許可リスト - 本番環境では、ポリシーファイルで allow リスト（/SCWM/* などのパターンに対応）を指定した strict ポリシープリセットを使用してください。従来の --allowed-transactions T1 T2 ... フラグも引き続き使用でき、ポリシーに加えて制限を適用します

5. ポリシープロファイル - --profile で表示するツールを制御します。exploration（読み取り専用）、operator（読み取り＋書き込み）、full（すべて。デフォルト）。sap_set_policy_profile を使ってセッションごとにプロファイルを切り替えることもできます。ただし、サーバーの --profile は上限です。セッションでさらに制限することはできますが、サーバーが許可する範囲を超えて権限を付与することはできません。

6. ツールタグ - ポリシープロファイルでフィルタリングできるよう、すべてのツールに read または write のタグが付いています。また、すべてのツールに MCP の readOnlyHint／destructiveHint アノテーションが付いているため、クライアントは適切な UI ヒントを表示できます。

7. 保存の確認 - sap_send_key("F11") と sap_send_key("Save") では、MCP エリシテーションによる明示的なユーザー確認が必要になりました。クライアントがエリシテーションに対応していない場合、確認なしで実行されるのではなく、保存がブロックされます。

8. 確認ポイント - サーバーが実行する前にユーザーのブロッキング承認を必要とする、書き込み操作の名前付きカテゴリです。save（F11／Save キー、および wnd[0]/tbar[0]/btn[11] の保存ツールバーボタン）は常に有効です。transactions、batch_fields、field_writes、all_writes、attach は、sap_set_confirmation_points を使ってセッションごとに有効化するか、--confirm POINT [POINT ...] を使ってすべてのセッションで有効化できます。attach は「はい／いいえ」の選択ではありません。sap_connect_existing を使うと、エージェントが作業する SAP セッションをユーザーが選択できます（--confirm attach を指定すると、すべてのチャットで有効になります）。

   ゲートはミドルウェアによってサーバー側で適用されるため、実験的な --code-mode サンドボックス内を含め、エージェントの動作にかかわらず適用されます。ポイントの追加は確認なしで行われますが、セッションのポイントを削除する際は、先にユーザーへ確認します。また、--confirm で設定したポイントは削除できません。ユーザーが拒否するとエラーが返され、何も実行されません。エリシテーションに対応していないクライアントではフェイルクローズとなり、確認が必要な呼び出しは未確認のまま実行されず、エラーになります。すべての確認は、結果（accepted、declined、unsupported_client）とともに監査ログに記録されます。

   これらのプロンプトはクライアント側で表示する必要があります。Claude Code CLI は対応しています。一方、Claude Code デスクトップアプリ（2026-10-19 にテスト）では、表示されないまま数ミリ秒以内にすべて拒否されたため、そこでサーバー経由の保存を承認することはできません。その場合、サーバーはユーザーが拒否したとは報告せず、ダイアログが表示されなかったと伝えます。確認ポイントを参照してください。

   エリシテーションに対応していないクライアントでは、ポイントの削除もフェイルクローズになります。そこで有効化したポイントは再び無効にできないため、セッションが終了するまで、そのカテゴリ全体がブロックされます。ポイントは sap_disconnect の後も維持されます。ポイントの有効期間は SAP 接続ではなく、MCP セッションです。

   all_writes は、選択、スクロール、ナビゲーションなど、業務データを変更しないヘルパーを含め、write タグが付いたすべてのツールを対象とします。これは意図的に厳格で、頻繁に確認を求めます。この設定では、sap_send_key("F11") に対して2回（カテゴリに対して1回、変更されていない保存ゲートに対して1回）確認が求められます。

9. 監査ログ - --audit-log FILE を指定すると、すべてのツール呼び出し（名前、引数、所要時間、結果、およびチャットが紐付けられている SAP システム、クライアント、ユーザー）が JSON Lines 形式で書き込まれます。引数に含まれるシークレットは自動的にマスクされます。

10. 認証情報の安全な解決 - sap_connect は .env ファイル（SAP_USER、SAP_PASSWORD、SAP_CLIENT、SAP_LANGUAGE）から認証情報を解決します。パスワードが MCP ツールのパラメーターとして受け付けられることはなく、クライアントログ、ツール呼び出し履歴、監査ログにも表示されません。使用を開始するには、.env.example を .env にコピーしてください。

11. ID の検証と正規化 - ユーザーが指定した SAP ウィンドウおよび要素の ID は、findById() の呼び出し前に検証されます。wnd[0]/usr/... のような標準 ID を使用できるほか、/app/con[0]/ses[0]/wnd[0]/usr/... のような完全なセッションパスは短縮形式に自動的に正規化されます。

12. HTTP ホストとオリジンのチェック - --transport http を指定した場合、localhost、127.0.0.1、バインドされたアドレス、または --allowed-host 以外のホスト名を宛先とするリクエストは拒否されます（421）。これにより、ウェブページが自身のホスト名をこのマシンに向ける（DNS リバインディング）ことでサーバーを利用するのを防ぎます。別のオリジンからのブラウザーリクエストも、--allowed-origin に登録されていない限り拒否されます（403）。localhost 上のページはローカルとして扱われます。MCP クライアントは Origin を送信しないため、影響を受けません。デフォルトのトランスポートである stdio には、ネットワーク経由の接点はありません。

本番環境での推奨事項

• 信頼できないユーザーには決して公開しないでください
• 探索やクエリには読み取り専用モードを使用してください
• 自動化にはトランザクションの許可リストを設定してください
• SAP 側で監査ログを有効にしてください
• 最小限の権限を持つ専用サービスアカウントを使用してください
• スクリプト実行はグローバルではなく、ユーザーごとに有効にしてください — sapgui/user_scripting_per_user と S_SCR 権限を使用すると、指定したユーザーにスクリプト実行を制限できます（スクリプト実行が制限されている環境への導入を参照）
• 隔離されたシステム（テスト／サンドボックス。本番環境ではないもの）で実行してください

SAP のライセンス

以下について、SAP のライセンス契約を確認してください。

• 自動アクセスとスクリプト実行
• 間接アクセスに関する考慮事項
• 指名ユーザーと同時接続ユーザーのライセンス

ワークフローの例

品目マスタを表示する

# Claude would execute these tools:
sap_connect("D01 - Development System")
sap_execute_transaction("MM03")
sap_set_field("wnd[0]/usr/ctxtRMMG1-MATNR", "MAT-001")
sap_send_key("Enter")
# Select views...
sap_send_key("Enter")
description = sap_read_field("wnd[0]/usr/txtMAKT-MAKTX")

購買発注一覧を抽出する

sap_execute_transaction("ME2M")
sap_set_field("wnd[0]/usr/ctxtEN_LIFNR-LOW", "1000")  # Vendor
sap_send_key("Execute")  # F8
data = sap_read_table("wnd[0]/usr/cntlGRID1/shellcont/shell", max_rows=50)

販売伝票に移動する

sap_execute_transaction("VA03")
sap_set_field("wnd[0]/usr/ctxtVBAK-VBELN", "12345")
sap_send_key("Enter")
# Read header data
customer = sap_read_field("wnd[0]/usr/subSUBSCREEN.../txtVBAK-KUNNR")
# Navigate to items
sap_press_button("wnd[0]/usr/tabsTAXI_TABSTRIP.../tabpT\\01")
items = sap_read_table("wnd[0]/usr/.../cntlGRID1/shellcont/shell")

カスタマイジングテーブル（GuiTableControl）を絞り込む

# In SPRO or SM30 table maintenance view
# Use Selection -> By Contents to filter
sap_select_menu("wnd[0]/mbar/menu[3]/menu[0]")    # Selection > By Contents
# Select the field to filter on, enter value
sap_select_table_row("wnd[1]/usr/tblSAPLSVIXTCTRL_SEL_FLDS", 0)
sap_send_key("Enter")
sap_set_field("wnd[1]/usr/.../txtQUERY_TAB-BUFFER[3,0]", "EXTSYS001")
sap_send_key("Execute")
# Read the filtered table
data = sap_read_table("wnd[0]/usr/tblSAPLBD41TCTRL_V_TBDLS")

フォームに一括入力して検証する

sap_set_batch_fields(
    {
        "wnd[0]/usr/ctxtFIELD1": "VALUE1",
        "wnd[0]/usr/txtFIELD2": "VALUE2",
    },
    validate=True,
    skip_readonly=True,
)
# Returns per-field results plus post-Enter screen feedback

変更前にユーザーに内容を表示する

「国 GR を追加する前に、値を表示してください。」

# Read-only: renders the current screen plus the pending values.
sap_preview(
    note="About to add country GR to V_T005",
    pending_fields={
        "Country Key (V_T005-LAND1)": "GR",
        "Name": "Greece",
        "Currency": "EUR",
    },
)
# The user confirms in chat, then the agent writes and saves:
sap_set_batch_fields({...}, validate=True)
sap_send_key("Save")   # still requires explicit confirmation via elicitation

プロジェクト構成

mcp-sap-gui/
├── docs/
│   ├── CLIENTS.md             # Client-specific MCP setup notes
│   ├── OVERVIEW.md            # Product overview and roadmap direction
│   └── TOOLS.md               # Full MCP tool catalog
├── scripts/
│   └── check_docs.py          # Markdown link checker used by docs workflows
├── src/
│   └── mcp_sap_gui/
│       ├── __init__.py        # Package exports
│       ├── server.py          # MCP server implementation (tool definitions)
│       ├── session_manager.py # Per-client SAP session isolation
│       ├── sap_controller.py  # Facade class (composes all mixins)
│       ├── models.py          # VKey enum, SessionInfo, exceptions
│       ├── controller.py      # Base controller (connection, navigation, screen info)
│       ├── fields.py          # FieldsMixin (read/write fields, buttons, combos)
│       ├── tables.py          # TablesMixin (ALV grid + TableControl operations)
│       ├── trees.py           # TreesMixin (tree read, expand, select, click)
│       ├── discovery.py       # DiscoveryMixin (popups, toolbars, screenshots)
│       ├── confirmation.py    # Confirmation points + blocking-confirmation middleware
│       └── preview.py         # sap_preview text + Prefab card builders
├── tests/
│   ├── test_sap_controller.py # Controller unit tests
│   ├── test_confirmation.py   # Confirmation points: gate, tool, CLI floor
│   ├── test_preview.py        # sap_preview builders + card/text branches
│   └── test_server.py         # Server security & routing tests
├── examples/
│   └── basic_usage.py         # Direct controller example
├── .mcp.json                  # MCP server config (auto-detected by Claude Code)
├── CONTRIBUTING.md            # Contribution guidelines for public changes
├── LICENSE                    # MIT license
├── pyproject.toml
├── uv.lock                    # Dependency lock file (managed by uv)
└── README.md

トラブルシューティング

「SAP GUI に接続できません」

• SAP Logon Pad、SAP Business Client、または別の SAP GUI セッションが実行中であることを確認してください
• SAP GUI のオプションで SAP GUI Scripting が有効になっていることを確認してください

「スクリプト実行が無効です」エラー

• sap_list_connections は、scripting_disabled: true でセッションのないシステムを報告します
• サーバー側でスクリプト実行を有効にしてください：RZ11 → sapgui/user_scripting = TRUE
• SAP Basis 管理者の対応が必要です
• 組織でスクリプト実行をグローバルに有効にできない場合は、ユーザーごとの有効化や読み取り専用での有効化方法について、スクリプト実行が制限されている環境への導入を参照してください

「要素が見つかりません」

• sap_get_screen_elements() を使用して、利用可能なフィールド ID を確認してください
• カスタマイズの違いにより、フィールド ID は SAP システムごとに異なります

起動時の COM エラー

• 依存関係がインストールされていることを確認してください：uv sync
• COM の登録に問題がある場合は、uv run python -m win32com.client.makepy を実行してください

「MCP クライアントに SAP ツールが表示されません」

• クライアントがプロジェクトのルートからサーバーを起動していることを確認してください
• MCP の設定を変更した後は、MCP クライアントを再起動してください
• 環境と依存関係を準備するため、先に uv sync を実行してください

読み取り中に SAP Logon が終了する

• SAP GUI 8.00 と 0.5.0 の組み合わせでは、テーブルコントロールやクラシックリストの読み取り時に SAP Logon が終了することがあります。0.5.1 にアップグレードしてください（issue #22）
• 1 回の呼び出しによる読み取りで失敗する別の SAP GUI ビルドでは、MCP_SAP_GUI_DISABLE_OBJECT_TREE を使って呼び出し箇所ごとに無効にし、MCP_SAP_GUI_TRACE_FILE で呼び出し箇所を特定してください。動作に問題のある SAP GUI ビルド向けのスイッチを参照してください

「ツールは利用できますが、操作がブロックされています」

• サーバーが --read-only を指定して実行されているか確認してください
• トランザクションポリシーによってブロックされているか確認してください。エラーには有効なプリセットが示されます。ポリシーファイル（--policy-file。詳細はセキュリティに関する考慮事項を参照）でトランザクションを許可するか、別の --policy-preset を選択してからサーバーを再起動してください。セッション内からポリシーを変更することはできません
• サーバーを --allowed-transactions を指定して起動したか確認してください

開発

# Install all dependencies (dev + screenshots)
uv sync --extra dev --extra screenshots

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

関連情報

• SAP GUI Scripting API のドキュメント
• MCP 仕様
• 貢献ガイド
• セキュリティポリシー
• クライアント設定ガイド
• ツールカタログ
• プロジェクト概要

ライセンス

MIT。詳細は LICENSE をご覧ください。

免責事項

このプロジェクトは SAP SE との提携、承認、またはスポンサー関係にありません。SAP、SAP GUI、および記載されているその他の SAP 製品は、SAP SE の商標です。

SAP システムでこのソフトウェアを使用する場合は、SAP のライセンス契約および組織のセキュリティポリシーを遵守してください。