io.github.kts982/mcp-sap-gui

MCP SAP GUI Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with SAP GUI for Windows through the SAP GUI Scripting API.

It is client-agnostic: if your MCP client can launch a local stdio server, it can use this project. Examples in this README use Claude because the setup is easy to demonstrate, but the same server can be used from Codex, GitHub Copilot, Gemini CLI, and similar MCP-capable tools.

Current release: 0.5.1 for local Windows use over MCP stdio.

Status

• GitHub workflows are included for CI, Docs, Dependency Audit, and tag-based Release.
• Primary repository: GitHub (kts982/mcp-sap-gui).

What's New

0.5.1 — a crash fix for SAP GUI 8.00, and screens that say more.

• No more SAP Logon crashes on SAP GUI 8.00. On 8.00, reading a table control or a classic list in one call could take SAP Logon down with every session in it (issue #22). The cause was one property in that call: the server no longer asks for it and reads checkboxes one by one, still about 3x faster than reading cell by cell. Two environment variables, contributed by @nelz0n in #23, turn the one-call read off per call site and trace each call to a file, for any other SAP GUI build that misbehaves. Which SAP GUI releases SAP still supports, and what needs which: SAP GUI Versions.
• Screen info names sub-screens and the cursor. Every action response lists the active window's sub-screens (subscreens, as program:dynnr) and the field the cursor is in (cursor), so an RF step, a tab page or a redisplay that only moves the cursor shows without a screenshot.
• Table controls say where their data ends. sap_read_table on a table control reports empty_rows_from, the first padding line: total_rows also counts the empty lines that pad an SM30 view.
• Confirmed writes say so. After you approve a save or another confirmation point, the result carries confirmed_by_user: true, so the agent can tell an approved write from an ungated one.

0.5.0 — the SAP GUI Scripting API, used to the full. This round went through the 8.10 Scripting API guide on a trial system and closed the gaps it found:

• Much faster on large screens. On SAP GUI 7.70 PL3 or later a whole screen, popup, list page or table control is read in one call (GetObjectTree): a 1,139-cell list page takes 0.2 s instead of 4.7 s. Older releases fall back to reading element by element.
• Value help that agents get right. F4 popups are recognised for what they are (hit list, restriction dialog, date picker, time picker) and never auto-cancelled, and a rewritten search_help guide covers each case. Dropdowns are set with sap_set_field and sap_set_batch_fields by key or text, and discovery shows their selected key instead of 200 padded characters.
• Safer popups. SAP's message popups are recognised in any logon language, and only an information message is ever auto-confirmed: a warning standing between you and a save is always left to you.
• Keys that mean what they say. sap_send_key refuses a key the screen does not accept and lists the ones it does, and Ctrl+F / Ctrl+G / Ctrl+P now send Find / Find next / Print (they sent Ctrl+F8 to Ctrl+F10 before).
• More of SAP's own metadata. Session info reports the SAP GUI release and whether the server only allows read-only scripting (write tools then refuse up front); ALV cells report their type, error or warning state, F4 help and hotspots; an ALV toolbar menu lists its items when it opens; a status message with a long text says so, and pressing the status bar opens it.
• SAP Business Client (experimental). Sessions of Business Client's embedded SAP GUI are discovered next to SAP Logon's. Details: SAP Business Client.

Changed behaviour when upgrading: discovery elements no longer carry visible (SAP GUI Scripting has no such property, so it was always true); F4 hit lists are classified list instead of information; a key the screen does not accept returns an error with available_keys instead of a COM error.

0.4.0 — shaped by two days of real agent work on a live system. The lesson was that token cost per call hurts more than missing tools, and that a few screens could not be reached at all:

• Lighter responses. A table control is one discovery element instead of one per cell (an SM30 screen went from 231 elements to 3), element IDs come back in the short wnd[0]/... form, and batch fills and popup actions report what matters instead of echoing everything.
• sap_read_list reads a classic report list (WRITE output, F4 hit lists) as lines of text with list colours and paging — 43 lines instead of 492 label elements, and no screenshot needed.
• View clusters work. Docking containers (wnd[0]/shellcont) are valid IDs and discovery points to them, so the dialog structure of SM34 and most IMG activities can be navigated. A new SM30 transaction guide covers table maintenance and view clusters end to end.
• Your transaction policy. Presets (default, abap-dev, strict) plus a policy file with glob patterns replace the hard-coded blocklist. Details: Security Considerations.
• Popups announce pre-filled values. When an action opens a popup, its response already says what the popup is and which inputs hold values you never chose — such as a customizing request pre-filled with another project's request.
• Screenshots to a file. sap_screenshot(save_path=...) writes a full-resolution PNG for documents and never overwrites a file.

sap_preview — see it before it happens. The agent can now show you an approval card at any checkpoint: before a batch write, before saving, or whenever you ask ("before adding country GR, show me the values"). It carries the current screenshot, session context, and the exact values about to be written — password-shaped values masked. On MCP Apps hosts (VS Code Copilot Chat) it renders as a rich inline card; everywhere else you get the same summary as text plus the screenshot. Saving still goes through the confirmation gate. Details: Rendered Preview Cards.

Confirmation points — nothing is written without you. Tell the agent once ("ask me before every field write") and the server enforces it: sap_set_confirmation_points activates categories of write operations that pause for your explicit approval before anything reaches SAP. Enforced server-side by middleware — declining blocks the call no matter what the agent does, removing a gate asks you first, and admins can pin gates for every session with --confirm. Details: Security Considerations.

What This Does

This server allows AI assistants to:

• Connect to SAP systems (like double-clicking in SAP Logon Pad)
• Execute transactions (MM03, VA01, /SCWM/MON, etc.)
• Read and write screen fields, checkboxes, radio buttons, comboboxes, and tabs
• Use F4 value help: hit lists, restriction dialogs, date and time pickers
• Select menu items from the menu bar (Table View, Edit, Selection, etc.)
• Navigate through SAP screens using keyboard keys and buttons
• Extract data from ALV grids (GuiGridView) and classic table controls (GuiTableControl)
• Read classic report lists (WRITE output) as text, including the colour of a line
• Interact with ALV toolbar buttons and context menus
• Read and interact with tree controls (TableTree, ColumnTree, SimpleTree), including the docked dialog structure of view clusters
• Take screenshots of SAP windows, inline or saved as a full-resolution file
• Discover screen elements for automation
• Show you previews before writing, and pause for your approval at confirmation points you choose

Example Conversation

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."

Quick Start

1. Install uv (it ships with uvx), if not already installed:

pip install uv

2. Start SAP Logon Pad and open an SAP GUI session, or at least have SAP Logon running.

3. Configure your MCP client to launch this server. No clone or manual install needed — uvx fetches the released package from PyPI and runs it in an isolated environment:

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

(Working from a source checkout instead? See Installation.)

4. Try one of these prompts:

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 intentionally does not accept a password parameter. The safer pattern is to log in through SAP GUI first and then attach with sap_connect_existing.

Requirements

• Windows (SAP GUI only runs on Windows)
• SAP GUI for Windows installed
  • Live compatibility verified with SAP GUI for Windows 8.10 64-bit Patch 0. SAP supports 8.10 until 30 June 2029 and 8.00 until 12 January 2027 (restricted support until 31 July 2027); 7.70 and older are out of SAP support and run best effort. Dates, sources and what needs which release: SAP GUI Versions
  • 7.70 Patch Level 3 or later reads a whole screen, popup, list page or table control in one call (GetObjectTree); older releases fall back to reading element by element, which is much slower on large screens (seconds instead of a fraction of a second for a full list page)
• SAP Logon Pad running, or a SAP GUI session hosted by SAP Business Client (experimental, see below) or another embedded SAP GUI (for COM connections)
• SAP GUI Scripting enabled on your SAP systems
• Python 3.10+
• uv (recommended Python package manager)

SAP Business Client (experimental)

• Classic transactions in SAP Business Client run in embedded SAP GUI for Windows, so the server-side scripting parameter is still required. sapgui/nwbc_scripting gives read-only scripting (same effect as sapgui/user_scripting + sapgui/user_scripting_set_readonly): write tools refuse, and grids cannot be scrolled, so a table read stops at the rows on screen.
• Sessions are discovered through the SAP GUI server process's COM Running Object Table entries (SAPGUISERVER-<pid>), next to the usual SAP Logon entry. sap_list_connections reports host: "sapguiserver" for them.
• Tabs of one Business Client window are sessions of one connection; a second system is a second connection.
• Business Client connections have no SAP Logon description; the list shows the system and client instead (e.g. DEV (100)).
• Pressing Back repeatedly closes the tab instead of landing on the SAP Easy Access menu (SAP Business Client FAQ).
• Fiori Launchpad connections may render a transaction as SAP GUI for HTML; such a transaction is invisible to scripting.

Supported Scope

Supported:

• SAP GUI for Windows via the SAP GUI Scripting COM API
• MCP stdio (default) and streamable HTTP transports
• Per-client session isolation (multiple MCP clients can hold independent SAP sessions)
• Interactive use from MCP-compatible clients
• Read and write SAP GUI automation within the permissions of the logged-in SAP user

Not yet available:

• SAP GUI for Java or SAP GUI for HTML
• Browser-based Fiori automation
• Unattended multi-user production orchestration

Enabling SAP GUI Scripting

SAP GUI Scripting must be enabled both client-side and server-side:

Client-side (SAP GUI Options):

1. Open SAP GUI → Options → Accessibility & Scripting → Scripting
2. Check "Enable scripting"
3. Optionally uncheck "Notify when a script..." for smoother automation

Server-side (SAP System):

• Transaction RZ11 → Parameter sapgui/user_scripting → Set to TRUE
• Requires SAP Basis administrator access

Deploying Where Scripting Is Restricted

Many organizations disable SAP GUI Scripting globally as a hardening default. Enabling it does not have to be all-or-nothing: SAP ships graduated server-side controls that let a Basis team enable scripting narrowly — typically for named users on a development system — while keeping it off for everyone else.

Profile parameter (RZ11/RZ10)	Effect
sapgui/user_scripting = TRUE	Master switch; required for any scripting
sapgui/user_scripting_per_user = TRUE	Scripting works only for users holding authorization object S_SCR (class BC_A, activity 16); all other users stay blocked (SAP Note 983990)
sapgui/user_scripting_set_readonly = TRUE	Scripts may read screen state but cannot send anything that changes server state (SAP Note 692245)
sapgui/user_scripting_force_notification = TRUE	Users always see a notification/consent dialog when a script attaches; cannot be suppressed in local SAP GUI options (SAP Note 3591984)
sapgui/user_scripting_disable_recording = TRUE	Blocks recording of new scripts; playback still works

Useful facts when proposing this to a Basis/security team:

• Per-user and read-only modes are combinable since SAP GUI 7.40 PL17 / 7.50 PL4: full API for S_SCR holders, read-only for everyone else (SAP Note 2565390).
• On a read-only session this server reports scripting_read_only: true in the session info and refuses every write tool up front with the reason, instead of letting each action fail inside SAP GUI. All read tools keep working.
• A dynamic RZ11 change to sapgui/user_scripting is not persistent — it reverts at the next application server restart, which suits a time-boxed evaluation on a development system.
• Server-side, scripted actions run under the SAP user's normal authorizations and appear in logs as ordinary user activity. The user's authorization profile is the effective security boundary — pair a dedicated minimal-authorization account with this server's transaction policy (--policy-preset, --policy-file), --profile, and --audit-log options for defense in depth.
• Authoritative reference: SAP GUI Scripting Security Guide (help.sap.com).

Why the Scripting API is required at all: SAP GUI for Windows draws dynpro screens on a custom canvas that exposes no usable structure to Windows UI Automation or other accessibility APIs — the Scripting API is the only structured way to read and drive SAP GUI screens. Commercial RPA products have the same dependency and fall back to screenshot/OCR-based automation when scripting is disabled; this project deliberately avoids that approach because it is imprecise and brittle.

Installation

From PyPI (recommended for users)

Nothing to clone. uvx downloads the latest release and runs it in an isolated environment:

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

The [screenshots] extra adds screenshot optimization (reduces screenshot size by 70-90%) and is recommended. Point your MCP client at uvx with argument mcp-sap-gui[screenshots] — see MCP Setup below.

From source (for development)

# 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 note for source checkouts: while an MCP server launched from this checkout is running, its process holds locks on native DLLs in .venv (pywin32, watchfiles). Running uv sync or upgrading dependencies during that time can fail with "Access is denied" or leave .venv half-updated — stop or restart the MCP client first, then sync. If two MCP clients (e.g. Claude Code and VS Code) launch the server from the same checkout, point the second one at an isolated environment instead of the shared .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 users are unaffected — every uvx launch uses its own cached environment.)

Usage

Connection recommendation: prefer sap_connect_existing for already authenticated sessions. Use sap_connect mainly for SSO flows or to open the SAP login screen before the user completes manual login.

Running the MCP Server Directly

# 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 (for team/remote use, binds to localhost)
uv run python -m mcp_sap_gui.server --transport http

# HTTP on custom host/port
uv run python -m mcp_sap_gui.server --transport http --host 0.0.0.0 --port 9000

# 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

# 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 Setup

This server communicates over stdio (stdin/stdout JSON-RPC), which is the standard MCP transport. You don't need to configure ports or URLs — the MCP client starts the server process and talks to it directly.

For any client, the core launch configuration is the same:

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

Running from a source checkout instead of PyPI? Use uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server as the command.

Client Setup Links

• Claude Code / Claude Desktop: setup examples are included below
• Codex: configure an MCP server in Codex and point it at the command above. Official MCP docs: https://developers.openai.com/learn/docs-mcp
• GitHub Copilot: configure a local MCP server in Copilot Chat / agent mode. Official docs: https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp
• Gemini CLI: add the server under mcpServers in your Gemini CLI settings. Official docs: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

Below are full examples for the most common local SAP GUI setup paths.

For a client-by-client setup guide, see docs/CLIENTS.md.

---

Option 1: Claude Code (Recommended for development)

The repository includes a .mcp.json at the project root. When you open this project in Claude Code, the MCP server is automatically discovered — no manual configuration needed.

To use it:

cd mcp-sap-gui
claude

Claude Code will detect .mcp.json and start the SAP GUI MCP server automatically.

If you want to configure it globally for Claude Code (available in any project), add it to your user settings at ~/.claude/.mcp.json:

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

---

Option 2: Claude Desktop

Add to your Claude Desktop config file:

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

Standard mode:

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

Note: Running from a source checkout instead of PyPI? Use "command": "uv" with "args": ["run", "--directory", "<path-to-mcp-sap-gui>", "python", "-m", "mcp_sap_gui.server"] — the --directory flag is required so uv finds the project's virtual environment regardless of the working directory Claude Desktop uses.

Read-only mode (recommended when exploring/querying data):

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

With transaction whitelist (only allow specific transactions):

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

After editing the config, restart Claude Desktop for changes to take effect.

---

Option 3: Any MCP-compatible client

The server uses stdio transport. Point any MCP client at:

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

For a source checkout, use uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server instead.

---

Verifying the Setup

Once configured, you can verify the MCP server is working by asking Claude:

"List all available SAP GUI tools"

Claude should respond with the full list of sap_* tools. If SAP GUI is running, try:

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

Then try:

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

Built-in Agent Guidance

The server includes built-in navigation knowledge that helps any MCP client (Claude Code, Copilot, Cursor, Cline, etc.) use SAP GUI effectively:

• MCP Instructions — Injected into every client's system prompt during initialization. Covers screen discovery workflow, popup handling, table pagination, SPRO tree navigation, key reference, and common mistakes to avoid.
• docs://sap-gui-guide Resource — Detailed reference guide available on-demand via resources/read. Covers element types, ID naming conventions, transaction code formats, table type comparison, status bar messages, and step-by-step patterns for SPRO and table maintenance views.

These prevent common agent mistakes like guessing element IDs, ignoring popups, pressing F5 (="New Entries") when meaning to refresh, using double_click_tree_node in SPRO (which opens docs instead of executing the activity) or in a view cluster (where it does nothing), or reading a classic report list from a screenshot instead of with sap_read_list.

Available Tools

The server currently exposes 60 MCP tools.

Category	Count	What it covers
Connection & Policy	7	Connect to SAP, attach to open sessions, inspect sessions, disconnect, set policy profile, set confirmation points
Navigation	3	Execute transactions, send keys, inspect current screen
Fields & UI	13	Read/write fields, buttons, tabs, comboboxes, textedit, focus
Tables & Grids	17	ALV grids, TableControls, row selection, column info, cell ops
Popup / Toolbar / Shell / Lists	5	Popup inspection and handling, toolbar discovery, shell content, classic report lists
Trees	10	Read/search/expand/select/click SAP tree controls
Discovery	2	Screen element discovery and screenshots
Preview	1	Show the user the current screen plus the values the agent is about to write
Workflow Guidance	1	Return step-by-step guidance for known multi-tool SAP workflows
Transaction Guidance	1	Return a generic, read-first guide for supported SAP transactions

The most important patterns:

• sap_get_screen_elements to discover IDs instead of guessing
• sap_read_table to start with any SAP table/grid
• sap_read_list when a report prints a plain list instead of an ALV grid
• Every action response carries a short popup digest when a popup opened (classification, texts, button labels, and prefilled_inputs with a notice when inputs already hold values); sap_get_popup_window gives the full details and suggests a safe next step
• sap_handle_popup(action="auto") when you want the server to dismiss only clearly safe informational popups and otherwise leave the dialog untouched
• sap_preview before significant writes (batch field fills, F11 / Save) so the user sees the screen and the pending values first
• sap_set_confirmation_points to make categories of writes ask the user for approval before they run
• sap_get_workflow_guide when you want the proven sequence for a known workflow
• sap_get_transaction_guide when you want a generic guide for a supported transaction: /SCWM/MON (also warehouse monitor), or SM30 for table/view maintenance and view clusters (also SM34, view cluster)
• sap_read_tree plus search/expand helpers for SPRO-style navigation

For the full tool catalog, grouped by category with short descriptions, see docs/TOOLS.md.

Rendered Preview Cards

sap_preview is read-only and always returns a written summary plus the screenshot as an image, so it works in every MCP client. Clients that support the MCP Apps UI extension (for example VS Code Copilot) instead get a rendered card with the screenshot and a pending-values table. Install the optional extra to enable the card:

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

Restricted or offline networks: by default the card renderer is loaded from the jsDelivr CDN, so the card silently fails to render on workstations without outbound internet access. Set PREFAB_BUNDLED_RENDERER=1 in the server's environment to make the renderer self-contained (a ~6.3 MB inline resource, no third-party domains):

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

Security Considerations

This server provides powerful automation capabilities. Use responsibly.

Built-in Safeguards

1. Transaction Policy - Which transactions an agent may start. What is dangerous depends on who runs the server and against which system, so it is configurable:

   • --policy-preset default (the default) blocks user and role administration (SU01, SU10, SU01D, PFCG, SU53), logs and dumps (SM21, ST22), development and program execution (SE38, SA38, SE80, SE37, SE16N), and system administration (STMS, SCC4, RZ10, RZ11, SM36, SM49, SM69, SM59, STRUST, SICF, SM01, SM18, SM19). Customizing and display work (SM30, SM34, SPRO, SE16, SE11) stays open
   • --policy-preset abap-dev additionally allows SA38, SE11 and SE80, for developers testing their own programs
   • --policy-preset strict blocks everything the policy file does not allow
   • --policy-file policy.json adds to the preset: {"preset": "abap-dev", "block": ["ZHR*"], "allow": ["SM59"]}. Entries are codes or glob patterns (SU*, /SCWM/*); allow always wins over block. Without the flag the server reads $MCP_SAP_GUI_POLICY_FILE, else %APPDATA%\mcp-sap-gui\policy.json if it exists. Keep the file outside the agent's workspace
   • Two examples ship in examples/: policy.example.json starts from default, additionally blocks a customer namespace (ZHR*) and SE16, and allows ST22 for dump analysis; policy.strict.example.json is an allowlist for a display-only agent. To make one your per-user policy on Windows: New-Item -ItemType Directory -Force "$env:APPDATA\mcp-sap-gui"; Copy-Item examples\policy.example.json "$env:APPDATA\mcp-sap-gui\policy.json"
   • The policy is read once at startup and written to the audit log (with the file's SHA-256). No tool can change it, and a policy file that cannot be read stops the server instead of falling back to something more permissive
   • Case-insensitive matching; handles /n, /o, /* prefixes and whitespace
   • It is a guardrail against agent mistakes, not a security boundary: a blocked transaction can often be reached another way (a menu path, a screen you left open). The SAP user's authorizations are the boundary

2. OK-Code Bypass Prevention - Setting likely SAP command fields such as tbar[0]/okcd, txtOK_CODE, or similar command-code aliases to a blocked transaction is also blocked, preventing circumvention of the transaction policy

3. Read-Only Mode - --read-only flag disables all mutating operations (field writes, button presses, transaction execution, key sends, tree/table interactions)

4. Transaction Whitelist - For production use an allowlist: the strict policy preset with an allow list in the policy file (supports patterns such as /SCWM/*). The older --allowed-transactions T1 T2 ... flag still works and restricts on top of the policy.

5. Policy Profiles - --profile controls which tools are visible: exploration (read-only), operator (read + write), full (all, default). Profiles can also be switched per-session via sap_set_policy_profile — but the server --profile is a floor: a session can restrict itself further, never grant itself more than the server allows

6. Tool Tags - Every tool is tagged read or write for policy profile filtering. All tools carry MCP readOnlyHint/destructiveHint annotations so clients can display appropriate UI hints

7. Save Confirmation - sap_send_key("F11") and sap_send_key("Save") now require explicit user confirmation via MCP elicitation. If the client does not support elicitation, the save is blocked instead of proceeding silently.

8. Confirmation Points - Named categories of write operations that require blocking user approval before the server executes them. save (the F11 / Save key and the wnd[0]/tbar[0]/btn[11] Save toolbar button) is always on. transactions, batch_fields, field_writes and all_writes can be activated per session with sap_set_confirmation_points, or for every session with --confirm POINT [POINT ...].

   The gate is enforced server-side by middleware, so it applies no matter what the agent does — including inside the experimental --code-mode sandbox. Adding a point is silent; removing a session point asks the user first, and points set by --confirm cannot be removed at all. Declining returns an error and nothing is executed, and clients without elicitation support fail closed (the gated call errors instead of running unconfirmed). Every confirmation is written to the audit log with its outcome (accepted, declined, unsupported_client).

   On a client without elicitation support, removal fails closed too: a point activated there cannot be turned off again, so it blocks that whole category for the rest of the session. Points survive sap_disconnect — their lifetime is the MCP session, not the SAP connection.

   all_writes covers every write-tagged tool, including selection, scrolling and navigation helpers that change no business data — it is deliberately strict and noisy, and under it sap_send_key("F11") prompts twice (once for the category, once for the unchanged save gate).

9. Audit Logging - --audit-log FILE writes every tool call (name, arguments, timing, outcome) as JSON lines. Secrets in arguments are masked automatically

10. Secure Credential Resolution - sap_connect resolves credentials from a .env file (SAP_USER, SAP_PASSWORD, SAP_CLIENT, SAP_LANGUAGE). Passwords are never accepted as MCP tool parameters and never appear in client logs, tool-call history, or audit logs. Copy .env.example to .env to get started

11. ID Validation And Normalization - User-supplied SAP window and element IDs are validated before findById() is called. Standard IDs like wnd[0]/usr/... are accepted, and full session paths like /app/con[0]/ses[0]/wnd[0]/usr/... are normalized to the short form automatically.

Recommendations for Production Use

• Never expose to untrusted users
• Use read-only mode for exploration/queries
• Implement transaction whitelists for automation
• Enable audit logging on SAP side
• Use dedicated service accounts with minimal authorizations
• Enable scripting per-user, not globally — sapgui/user_scripting_per_user with the S_SCR authorization limits scripting to named users (see Deploying Where Scripting Is Restricted)
• Run on isolated systems (test/sandbox, not production)

SAP Licensing

Consult your SAP licensing agreement regarding:

• Automated access and scripting
• Indirect access considerations
• Named vs. concurrent user licensing

Example Workflows

Display Material Master

# 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")

Extract Purchase Order List

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)

Navigate Sales Order

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")

Filter Customizing Table (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")

Batch Fill And Validate A Form

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

Show The User What Is About To Change

"Before adding country GR, show me the values."

# 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

Project Structure

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

Troubleshooting

"Cannot connect to SAP GUI"

• Ensure SAP Logon Pad, SAP Business Client or another SAP GUI session is running
• Check that SAP GUI Scripting is enabled in SAP GUI options

"Scripting disabled" error

• sap_list_connections reports such systems with scripting_disabled: true and no sessions
• Enable scripting server-side: RZ11 → sapgui/user_scripting = TRUE
• Requires SAP Basis administrator
• Organization won't enable scripting globally? See Deploying Where Scripting Is Restricted for per-user and read-only enablement options

"Element not found"

• Use sap_get_screen_elements() to discover available field IDs
• Field IDs vary between SAP systems due to customization

COM errors on startup

• Ensure dependencies are installed: uv sync
• Run uv run python -m win32com.client.makepy if COM registration issues occur

"No SAP tools appear in my MCP client"

• Confirm the client is launching the server from the project root
• Restart the MCP client after changing its MCP configuration
• Run uv sync first so the environment and dependencies exist

SAP Logon exits during a read

• On SAP GUI 8.00 with 0.5.0, table-control and classic-list reads can take SAP Logon down: upgrade to 0.5.1 (issue #22)
• Another SAP GUI build that fails on the one-call read: turn it off per call site with MCP_SAP_GUI_DISABLE_OBJECT_TREE, and find the call with MCP_SAP_GUI_TRACE_FILE. See Switches for a misbehaving SAP GUI build

"The tool is available, but the action is blocked"

• Check whether the server is running with --read-only
• Check whether the transaction policy blocks it: the error names the active preset. Allow the transaction in a policy file (--policy-file, see Security Considerations) or pick another --policy-preset, then restart the server. The policy cannot be changed from inside a session
• Check whether you started the server with --allowed-transactions

Development

# 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/

Related

• SAP GUI Scripting API Documentation
• MCP Specification
• Contributing Guide
• Security Policy
• Client Setup Guide
• Tool Catalog
• Project Overview

License

MIT. See LICENSE.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by SAP SE. SAP, SAP GUI, and other SAP products mentioned are trademarks of SAP SE.

Use of this software with SAP systems should comply with your SAP licensing agreement and your organization's security policies.