mcp-sap-gui

MCP SAP GUI

MCP tools for one configured SAP GUI for Windows session. This repair uses Python MCP SDK 2.1.1 and serves both the published 2026-07-28 protocol (server/discover) and legacy initialization over stdio. The original seven tool names remain available; COM control tools and optional GuiXT InputScripts add alternatives to image recognition.

Install and select a session

Use Python 3.11–3.13 on an interactive Windows desktop with your licensed SAP GUI, a configured SAP Logon connection, and SAP GUI Scripting installed and enabled by your administrator. The implementation targets the public SAP GUI 8.00/8.10 scripting interface. CI checks Python and Windows bindings; actual SAP 8.00/8.10 systems have not been exercised in CI. Consult SAP's current platform/patch matrix for your installation. This does not support SAP GUI for Java or a headless SAP desktop.

python -m pip install .
Copy-Item .env.example .env
# Edit .env to select the intended session.
python -m sap_gui_server.server

For repeatable development use uv sync --frozen --python 3.13, uv run pytest, and uv build. build.bat builds from local source; setup.bat creates a template without prompting for or echoing a password. Node is optional and only needed for run.bat debug (MCP Inspector).

An existing authenticated session, including SSO, needs no password:

SAP_SESSION_ID=/app/con[0]/ses[0]
# Optional assertion, checked against the authenticated SAP user:
SAP_USER=YOUR_SAP_USER

Use the exact ID of a session reserved for automation. SAP GUI's scripting recorder displays the connection/session indexes. The server never chooses an arbitrary active window or the first existing session. To open a new connection instead, omit SAP_SESSION_ID and set SAP_CONNECTION to its exact SAP Logon description. New connections may use existing Windows/SAP SSO; optional SAP_CLIENT, SAP_USER, SAP_PASSWORD and SAP_LANGUAGE fill the login controls through COM. Passwords are never process arguments or log entries.

SSO uses the identity of the local Windows/SAP session. It does not infer the identity of a chat user, exchange a ChatGPT token, or implement remote Microsoft on-behalf-of authentication. Run a separate local server under each intended Windows user; no shared remote authentication endpoint exists here. This distinction is part of issue #8's remaining integration requirement.

For a custom installation set SAP_GUI_PATH to the installed saplogon.exe or its directory, for example C:\Program Files\SAP\FrontEnd\SAPGUI. This is used to start SAP Logon when its running COM object is absent. The default expects SAP Logon already running, avoiding a guessed 32-bit registry path (#3).

Scripting text reads use SAP control properties, not Win32 window captions, addressing the 64-bit text-reading report (#6). Password controls are redacted. Read-only scripting policies may permit reads but reject writes; the server reports that failure and never changes SAP security settings. SAP's scripting requirements and GUI documentation describe installation and administrator prerequisites.

Tools

Control IDs must start with wnd[N], such as wnd[0]/usr/ctxtFIELD; cross-session absolute IDs are rejected. These are public SAP ActiveX/COM scripting operations (#2), with typed methods rather than arbitrary COM method evaluation. See SAP's application API and session API.

Screenshot-capable tools accept return_screenshot: none (default), as_file, as_base64, as_imagecontent, or as_imageurl. The last spelling remains compatible but now returns a valid embedded PNG blob resource, not a fake remotely retrievable URL. Screenshots are physical pixels without double DPI scaling and are bounded to 30 million pixels / 7 MB. SAP_OUTPUT_ROOT must be an existing directory before file writes; as_file_target_folder must resolve inside it. Saving never overwrites an existing file. No screenshot is captured by default, so save_last_screenshot requires a preceding explicit screenshot request.

GuiXT (#1)

Install GuiXT/InputAssistant as appropriate for your licensed setup. Set GUIXT_PATH to the absolute guixt.exe and GUIXT_SCRIPT_ROOT to an existing directory containing reviewed InputScripts with simple names such as read_order.txt. Explicitly enable AllowExternalInput Yes in GuiXT's profile; the server does not alter it. The tool accepts a script name, verifies the root boundary, and invokes GuiXT with findsession=hwnd:'…' for the selected SAP window. No shell or caller-supplied command fragments are used.

GuiXT submissions are asynchronous. A successful result means the external invocation was accepted; it does not prove business-process completion. Inspect that same session and any script-specific output before issuing more input. There is no automatic retry or generic cancellation of a script already accepted by GuiXT. See the vendor's external InputScript contract, including the opt-in introduced in 2026 Q1 1.

Lifecycle and migration

All COM work runs in one serialized STA worker process. SAP_OPERATION_TIMEOUT defaults to 30 seconds (1–120). Cancellation or a deadline terminates only this server's worker process and refuses further work until the MCP server is restarted. An already-issued SAP action cannot be rolled back; inspect the session before resuming. No taskkill, process-name matching, global SAP termination, or automatic multiple-logon popup action remains. Closing MCP releases handles and leaves SAP sessions open. Explicit end_transaction may discard unsaved work in the chosen transaction.

Execution failures have isError=true, invalid inputs/unknown tools follow SDK error semantics, and stdout contains only MCP JSON-RPC. Tool arguments, form text, credentials and COM exception details are not logged. The local stdio process has the desktop privileges of its Windows user. Use a dedicated automation session and keep output/script directories under that user's control.

Version 0.2 replaces the broken SDK1 constructor/decorators and process-wide control behavior. SAP_SYSTEM is replaced by SAP_CONNECTION (a Logon description) or SAP_SESSION_ID; passwords are optional. File outputs now require a root. Old code importing internal controller methods should migrate to the named MCP tools. The integration helper uses the Python interpreter that invokes it; run it from the environment containing the package.

Validation and Docker

uv run ruff check ., uv run ruff format --check ., uv run pytest, and uv build validate source, controlled COM mocks, timeout/cancellation, real child-process modern/legacy protocol sessions, installed package discovery, and error behavior. Windows CI imports native bindings and captures a disposable test window. It does not log in to SAP, run a transaction on a real system, or prove SSO/GuiXT in your landscape.

The Dockerfile now builds from this checkout and runs a non-root protocol/discovery image. A Linux container cannot access an interactive licensed Windows SAP GUI. SAP tool calls in that image return an explicit platform error; use the native Windows package for automation. This corrects the invalid Dockerfile in #4 without claiming containerized SAP or a verified Glama deployment. Updating/claiming a third-party directory listing remains separate external work.

Before production use, on a disposable SAP client: verify the selected SSO identity and optional mismatch assertion; read text on your GUI patch; start a harmless transaction and verify another open session is untouched; exercise a control, screenshot and GuiXT script; cancel a long request and confirm no unrelated process closes. Record GUI version, patch, Windows build, scripting policies and outcomes. These native SAP acceptance gates remain explicit until tested.