Skip to main content
Glama
adam0thman

sapgui-mcp

by adam0thman
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

sap-gui-control

A Claude skill for interacting with SAP efficiently — by choosing the right channel for each step of a task rather than reaching for the GUI by reflex.

Most SAP work does not need a screen at all. The skill routes each step to the cheapest channel that can do it, and when the GUI genuinely is required it drives SAP GUI for Java in the background: no screenshots, no coordinate clicking, no stealing focus. You keep using your machine.

Channels

#

Channel

Script

Status

0

OS / SAPControl (no SAP login)

sap_control.py

unauthenticated calls verified live

1

RFC / BAPI

sap_rfc.py

verified live incl. write guards

2

Direct DB, read-only

sap_db.py

guard tested; connection unverified

3

ADT over HTTP

sap_adt.py

diagnosis verified; happy path unverified

4

OData / RAP

—

guidance

5

AX background GUI control

ax_okcode.swift

verified live

6

SAP GUI scripting

sap_script.sh

object model verified; live session unverified

7

Vision + mouse

(built-in)

last resort

Plus gui_preflight.sh, which says why GUI input is failing instead of leaving you to guess.

The decision table for picking between them — and for splitting one task across several — is in SKILL.md.

Related MCP server: SAP RFC MCP Server

What it does

SK=~/.claude/skills/sap-gui-control/scripts

# headless first — no GUI involved at all
creds exec <system-id> -- python3 $SK/sap_rfc.py info
creds exec <system-id> -- python3 $SK/sap_rfc.py table T000 MANDT,MTEXT --rows 5

# GUI, driven in the background
swift $SK/ax_okcode.swift probe "ECD (2)"
swift $SK/ax_okcode.swift run   "ECD (2)" "/nSE16"
swift $SK/ax_okcode.swift press "ECD (2)" "Back (F3)"

# why is input failing? (never guess)
bash $SK/gui_preflight.sh

Why it exists

Driving SAP GUI on macOS fails in ways that are invisible on screen, so an assistant tends to invent an explanation. Three separate sessions independently reported "a macOS Open/Save dialog is attached to the SAP GUI, blocking input." That dialog never existed. The real causes were:

  • the frontmost-app policy — a browser in front blocks clicks and typing; a terminal or IDE blocks typing but allows clicks. That asymmetry is diagnostic: a modal dialog would block both.

  • a SAP dynpro popup owning input — these are separate windows with AXModal=false and no attached sheet, so sheet/modal checks report "all clear" while the session is fully blocked.

  • sessions sharing identical geometry — several SAP windows open full-screen at the same coordinates, so a click lands on the topmost one, not the one you meant.

gui_preflight.sh distinguishes all three, so the answer is measured instead of guessed.

Install

cp -r skills/sap-gui-control ~/.claude/skills/

User-level on purpose — SAP work happens in many sessions and directories, not one repo. See INSTALL.md.

Requirements: macOS, SAP GUI for Java, and Accessibility permission for the calling process. The RFC script additionally needs pyrfc built against the SAP NW RFC SDK (it is not on PyPI). Credentials come only from creds exec; nothing secret is stored or printed.

What works, and what doesn't

Measured against SAP GUI for Java 8.10rev4 — not assumed:

Works with SAP in the background — reading the whole screen as text; writing text via AXSelectedTextRange + AXSelectedText; AXPress on buttons, including ones that round-trip to the SAP server; detecting a blocking popup via AXFocusedWindow; selecting text inside input fields.

Does not work — AXValue is settable nowhere and silently discards writes while reporting success (the trap that makes AX look impossible); AXFocused is likewise accepted and discarded; CGEvent.postToPid never arrives while the app is backgrounded; AXEnhancedUserInterface is not implemented; classic SAP list output exposes almost nothing to accessibility, so list content must come from RFC rather than screen-scraping.

Some SAP functions also call a frontend component that SAP GUI for Java does not implement — they fail silently, with the preflight reporting clear. SCC3's Monitor button is one.

History

This began as an MCP server with a cost-routing engine. That work is preserved at tag v0.1.0 and was removed from main: the capability people actually used was the skill, and the router had only one tier to route between. The genuinely hard-won part — the pyrfc / NW RFC SDK wiring — survives as sap_rfc.py.

License

MIT — see LICENSE.

Not affiliated with or endorsed by SAP SE. "SAP", "SAP GUI" and "S/4HANA" are trademarks of SAP SE.

Available Tools

1 tool
sap_executeA

Run an SAP task via the cheapest capable tier.

Args: task: logical task name (catalog key), e.g. "create_sales_order". system: creds index id of the target system. params: task parameters. env: environment of the system (dev|qas|prd|sbx); drives the prod guard. constraints: e.g. {"must_stay_in_live_session": true, "allow_prod": false}. mutating: whether this task changes SAP state. dry_run: validate/preview without committing.

ParametersJSON Schema
NameRequiredDescriptionDefault
envNounknown
taskYes
paramsNo
systemYes
dry_runNo
mutatingNo
constraintsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly covers mutation via the 'mutating' flag, non-committing preview via 'dry_run', and a production guard driven by 'env'. It does not detail error behavior or credentials, but the most safety-relevant behaviors are described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear summary sentence followed by a compact line-per-parameter Args block. It contains no filler, tautology, or redundant restatement of the schema, and the most important behavioral flags are easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All seven parameters are documented, required parameters are identifiable, and an output schema exists so return-value documentation is unnecessary. Remaining gaps are auxiliary details such as the available task catalog, exact prod-guard behavior, and error handling, which are not essential for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the schema only provides names, types, and defaults. The description compensates fully by explaining each parameter's meaning, including the task catalog-key concept, system as a creds index, env allowed values, constraints example, and the semantics of mutating and dry_run.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Run an SAP task') and resource ('SAP task' catalog key) with a routing hint about using the cheapest capable tier. It does not distinguish from siblings because none are provided, so it misses the top score only on the sibling-differentiation criterion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose statement: use this to run SAP tasks. However, there is no explicit guidance about prerequisites, when not to use it, or how it compares to alternatives. Since no sibling tools exist, the absence of alternative routing is less damaging, but the description still does not spell out usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedsap_execute
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so an agent cannot confuse it with any other tool. The tool's purpose is also clearly framed as a generic SAP task executor.

Naming Consistency4/5

The single name sap_execute is clear and uses a readable verb-style convention with an SAP prefix. However, with only one tool there is not enough surface to fully establish a consistent naming pattern.

Tool Count3/5

One tool feels thin for a server named sapgui-mcp, even though sap_execute is a broad, non-trivial gateway. The surface is borderline minimal rather than severely mismatched.

Completeness3/5

The execute tool covers task execution, including dry-run and production guards, but there is no tool for discovering available tasks, listing systems, or managing sessions. This leaves notable gaps and forces the agent to rely on prior knowledge of the catalog.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP SAP GUI Server

    mario-andreschak
    A
    license
    Not graded
    quality
    D
    maintenance
    Automates interactions with SAP GUI using the Model Context Protocol, allowing precise control of SAP transactions through tools like clicking, typing, scrolling, and transaction management.
    132
    MIT

  • SAP RFC MCP Server

    Time-90
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    An enterprise-grade MCP server that enables AI agents to execute SAP RFC functions and read business data securely through the Model Context Protocol.
    MIT

  • SAP MCP Server

    hugoconsulting
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to securely connect with SAP ABAP and BTP services, allowing execution of function modules, BAPIs, table reads, and various BTP operations through MCP.
    1
    Apache 2.0