mcp-sap-gui

# MCP SAP GUI Server

<!-- mcp-name: io.github.kts982/mcp-sap-gui -->

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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.4.0` for local Windows use over MCP `stdio`.

[![CI](https://github.com/kts982/mcp-sap-gui/actions/workflows/ci.yml/badge.svg)](https://github.com/kts982/mcp-sap-gui/actions/workflows/ci.yml)
[![Docs](https://github.com/kts982/mcp-sap-gui/actions/workflows/docs.yml/badge.svg)](https://github.com/kts982/mcp-sap-gui/actions/workflows/docs.yml)
[![Release](https://img.shields.io/github/v/release/kts982/mcp-sap-gui)](https://github.com/kts982/mcp-sap-gui/releases)

## 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.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](#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](#rendered-preview-cards).

<img src="docs/images/sap-preview-card.png" alt="sap_preview approval card rendered inline in VS Code Copilot Chat" width="640">

**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](#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
- 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](https://docs.astral.sh/uv/) (it ships with `uvx`), if not already installed:

```bash
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](https://pypi.org/project/mcp-sap-gui/) and runs it in an isolated environment:

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

(Working from a source checkout instead? See [Installation](#installation).)

4. Try one of these prompts:

```text
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 Logon Pad** running (for COM connections)
- **SAP GUI Scripting enabled** on your SAP systems
- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** (recommended Python package manager)

## 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).
- 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](https://help.sap.com/doc/97d2d0bc2ed248a4a85a0bec608704f8/800.13/en-US/sap_gui_scripting_sec_guide.pdf) (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