Skip to main content
Glama

Looking for a maintainer. This project may not receive updates. For SAP GUI for Windows, use sapgui.mcp.

SAP Web GUI MCP Server

Unittests Coverage Linting Formatting

An MCP (Model Context Protocol) server that lets an AI agent work in SAP Web GUI. It controls SAP through a Chrome browser, so it runs on Windows, macOS and Linux. You use it from Claude Desktop, Claude Code, or opencode. Because it drives the real SAP UI (not a headless API), it is especially well-suited for end-to-end testing, visual validation, and capturing screenshots for documentation. The MCP server works with both SAP R/3 and S/4. The WebGUI driver is less mature than the SAP GUI for Windows driver in sapgui.mcp.

Because every SAP screen is a browser tab, the agent can also switch to another tab while the first one is still updating, which allows concurrent workflows (see sap_session_bind in Capabilities).

Pairing with other MCPs

You can pair this GUI MCP with an ADT MCP like aibap.mcp. ADT MCPs and this GUI MCP complement each other in a two-agent vibe-coding setup: one agent writes ABAP via ADT, while a second agent drives this server to test the generated code in the real SAP UI, captures screenshots, and reports failures back.

Language-specific behaviour for some transactions

The core of this MCP is not language-specific, meaning it generally works with any SAP logon language. However, there is also built-in support for specific transactions like SE16 or ST22. These transaction-specific tools only work for certain logon languages, because the MCP server relies on button or column labels, which vary by language. We support English (EN), German (DE) and Italian (IT).

Under the hood

Are you a developer? Read ARCHITECTURE.md for codebase structure, request flow diagrams, and how to add new transaction tools. CONTRIBUTING.md covers running from source, tests and code style.

Setup

Setup is a linear path of five steps:

  1. Install the server (standalone executable, Docker, or from source).

  2. Create the SAP config file systems.json.

  3. Start Chrome with remote debugging.

  4. Register the server with your MCP client (Claude Code, Claude Desktop or opencode).

  5. Verify the setup and try a first prompt.

Docker users follow the Docker section instead of steps 1 and 4; they must still start Chrome themselves (Step 3).

Before you start, you need:

  • Google Chrome (the server drives it through the Chrome DevTools Protocol, CDP).

  • A VPN connection, if your SAP system is on an internal network.

  • Your SAP system's Web GUI must be reachable in a browser at https://<host>/sap/bc/gui/sap/its/webgui and you must be able to log in there with user and password. Ask your SAP Basis team to activate the ICF service /sap/bc/gui/sap/its/webgui if it is not.

NOTE

Why a separate credentials file? Most MCP servers put SAP credentials directly in the per-project MCP config (env block), which means re-entering them for every project. Here, credentials and SAP settings live in a single shared file (systems.json) that all Hochfrequenz SAP MCP servers read automatically - so this server and aibap.mcp both work with the same credentials without duplication. You can store credentials in plain text, but you can also refer to an environment variable.

WARNING

Special characters in passwords stored in a .json file: If your SAP password contains " or \ characters, you must escape them in the JSON config files: " becomes \" and \ becomes \\. For example, pass"word becomes "pass\"word" and do\main becomes "do\\main". Unescaped special characters will silently break the JSON and the MCP server will fail to start.

TIP

Windows file extensions: If file extensions are hidden in Windows Explorer, creating .mcp.json via right-click → New → Text File will produce .mcp.json.txt (or .mcp.json.json if you rename). Make sure "File name extensions" is checked in Explorer's View tab, then rename the file.

Step 1: Install the server

Pick one way to get the server. Each release on GitHub Releases provides standalone executables; each release also publishes a Docker image on ghcr.io.

Option A: Standalone executable (Windows, macOS - no Python needed)

Download the binary for your platform from GitHub Releases:

Platform

Binary

Windows (x64)

sapwebgui_mcp_windows_<version>.exe

macOS (Apple Silicon)

sapwebgui_mcp_macos_arm64_<version>

Each release also lists checksums.txt (SHA-256 of the binaries). Save the binary somewhere permanent and note its full path. You need it in Step 4. For example, if you saved sapwebgui_mcp_windows_<version>.exe to your Downloads folder, the path is C:/Users/YourName/Downloads/sapwebgui_mcp_windows_<version>.exe. Always use forward slashes (/) in JSON, not backslashes (\).

Windows blocks the .exe? Windows may flag an executable as downloaded from another computer. If you trust the file downloaded from our GitHub Releases, right-click it → Properties (Eigenschaften) → General (Allgemein). Under Security (Sicherheit), check Unblock (Zulassen), then Apply (Übernehmen) and try again. The checkbox only appears when Windows has marked the file as downloaded from another computer. This removes that download block; it does not override Smart App Control. If Smart App Control still blocks execution, contact your IT administrator rather than disabling protection.

Screenshot: the Unblock checkbox in Windows file properties

macOS Gatekeeper: If macOS refuses to run the binary, clear the quarantine attribute and make it executable: xattr -c sapwebgui_mcp_macos_arm64_<version> and chmod +x sapwebgui_mcp_macos_arm64_<version>.

There is no Linux binary. On Linux, use Option B.

The executable cannot start its own Playwright browser: it only supports BROWSER_MODE=connect (your own Chrome).

Option B: From source (all operating systems)

You need uv (it installs the right Python for you).

git clone https://github.com/Hochfrequenz/sapwebgui.mcp.git
cd sapwebgui.mcp
uv sync

This creates a virtual environment in .venv with the command run-sapwebgui-mcp-server. Note the full path of that command; you need it in Step 4:

OS

Path of the command

Windows

C:/path/to/sapwebgui.mcp/.venv/Scripts/run-sapwebgui-mcp-server.exe

macOS / Linux

/path/to/sapwebgui.mcp/.venv/bin/run-sapwebgui-mcp-server

To update later, run git pull and uv sync again. Contributors: see CONTRIBUTING.md for the development setup.

Step 2: Create the SAP config file (systems.json)

This file holds your SAP systems and credentials. It is shared with aibap.mcp - configure it once and all Hochfrequenz SAP MCP servers will use it. The file format is owned by sap-mcp-config; see there for the complete field reference, validation rules and YAML support.

The default location is:

OS

Default path

Windows

%USERPROFILE%\.config\sap-mcp\systems.json

macOS/Linux

~/.config/sap-mcp/systems.json

On Windows, open Windows Explorer and paste %USERPROFILE%\.config\sap-mcp into the address bar. Create the folder if it doesn't exist, then create a file called systems.json inside it. (Set SAP_CONFIG_FILE to use another path.)

{
    "default_system": "dev",
    "systems": {
        "dev": {
            "host": "https://your-sap-server:44300",
            "client": "100",
            "user": "your_username",
            "password": "your_password",
            "language": "DE"
        }
    }
}
  • The dictionary key ("dev") is the system key. The agent passes it as system_key to sap_login, and default_system names the key used when none is given.

  • host is the base URL of your SAP system. The server derives the Web GUI URL {host}/sap/bc/gui/sap/its/webgui from it. If your system uses a different Web GUI path, ask the agent to log in with that full URL (sap_login has a url parameter).

  • language must be DE, EN or IT (omitted means EN).

  • You do not need connection_name (that field belongs to SAP Logon, which this server does not use).

NOTE

tls_skip_verify: true makes sap_login accept a self-signed or internally-signed certificate in a Chrome you started yourself (applied over CDP, no restart needed). A Chrome that this server launches always accepts such certificates (it is started with --ignore-certificate-errors, see Step 3). Without the setting, a Chrome without that flag shows net::ERR_CERT_AUTHORITY_INVALID; sap_login then returns guidance. The setting applies to the whole Chrome (all tabs) until the server disconnects from it, also for later logins to other systems, so use it only with a Chrome profile dedicated to SAP (a separate --user-data-dir), never with your personal browsing profile.

IMPORTANT

After editingsystems.json, restart Claude Desktop, Claude Code, or opencode for the changes to take effect.

TIP

Don't want your password sitting in the file? A system's string fields - host, client, user, password, language, oauth2_client_id - may reference an environment variable instead, using ${env:VAR}:

"user": "${env:SAP_DEV_USER}",
"password": "${env:SAP_DEV_PASSWORD}"

The file then holds only structure - which systems exist and their hosts - so it is safe to commit and share with your team, while the credentials come from your environment or password manager. If a referenced variable is unset or empty, the first tool call that needs a credential - sap_login, for instance - fails with an error naming the variable, rather than logging in with an empty password.

For several systems, add more entries under systems. The agent then lets you choose one (the choose tool) and logs in with sap_login(system_key="qa"). If the system key is not found, an error lists the available keys.

Step 3: Start Chrome with remote debugging

The server controls a Chrome browser that you can see. Chrome must run with remote debugging enabled on port 9222 and with its own profile directory (--user-data-dir; without it Chrome joins your running Chrome and ignores the debugging flag).

Windows:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\temp\chrome-debug" --ignore-certificate-errors

If Chrome was installed only for your user, use "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe" instead. If the command fails, see Finding your Chrome path.

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="/tmp/chrome-debug" --ignore-certificate-errors

Linux:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --ignore-certificate-errors

Leave this Chrome window open. Check that it works (open http://localhost:9222/json/version in another browser, or run):

Invoke-WebRequest -Uri 'http://localhost:9222/json/version' -UseBasicParsing

On macOS/Linux: curl http://localhost:9222/json/version. You should see JSON. If you get a connection error, make sure you included --user-data-dir.

NOTE

On Windows this step is optional. If no Chrome answers on port 9222, the server finds Chrome and starts it with these flags itself (profile directory CHROME_USER_DATA_DIR, default <tempdir>/chrome-debug; set CHROME_PATH if Chrome is not found). On macOS and Linux the server cannot start Chrome: you must start it yourself.

If your Chrome listens on another port, set CDP_URL (see the environment variables).

Step 4: Register the server with your MCP client

Register the server once with the client you use. The server name is up to you; this guide uses sap-webgui. Below, <command> is the full path you noted in Step 1 (the .exe, the macOS binary, or the run-sapwebgui-mcp-server command of your source checkout).

Claude Code

Recommended: register once for all projects (user scope). Run this in PowerShell, bash or zsh:

claude mcp add --scope user sap-webgui '--' C:/path/to/sapwebgui_mcp_windows_<version>.exe

Together with systems.json, this is all Claude Code needs - no .mcp.json in any project folder. If you add environment variables with -e (see Optional environment variables), two details matter:

  • Keep the server name (sap-webgui) before -e. The -e option accepts several values, so a name placed after it is read as a second environment variable and the command fails with error: missing required argument 'commandOrUrl'.

  • Keep the quotes around '--'. If Claude Code was installed through npm, claude is a PowerShell script, and PowerShell silently drops an unquoted -- before passing the arguments on. -e then swallows the executable path and the command fails with the same error. This works in PowerShell, bash and zsh (in bash or zsh, '--' and -- are equivalent). In cmd.exe, single quotes are not quoting characters, so write a plain -- instead.

On macOS or Linux, use your <command> path instead of the .exe path. If Claude Code still starts an old or broken registration instead of the global one, see Claude Code ignores the global registration.

Alternative: per project. Add to .mcp.json in your project root:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "C:/path/to/sapwebgui_mcp_windows_<version>.exe",
            "args": [],
            "env": {}
        }
    }
}

Claude Desktop

Add to claude_desktop_config.json. On Windows, press Win+R, type %APPDATA%\Claude and press Enter. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json. If claude_desktop_config.json does not exist, create a new text file with that exact name (make sure it ends in .json, not .json.txt). If the file already has content, add sap-webgui to the existing mcpServers object.

{
    "mcpServers": {
        "sap-webgui": {
            "command": "C:/path/to/sapwebgui_mcp_windows_<version>.exe",
            "args": [],
            "env": {}
        }
    }
}

Restart Claude Desktop after saving.

opencode

Add to opencode.json in your project root:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sap-webgui": {
            "type": "local",
            "command": ["C:/path/to/sapwebgui_mcp_windows_<version>.exe"],
            "enabled": true,
            "environment": {}
        }
    }
}
TIP

Inopencode.json, you can use either forward slashes (C:/path/to/...) or double-escaped backslashes (C:\\path\\to\\...) in the command path. Single backslashes will break the JSON silently.

Optional environment variables

Most setups need none. To set one (for example CDP_URL, CHROME_PATH or GITHUB_PAT, see the environment variables):

  • Claude Code (command line): add -e NAME=value between the server name and '--', for example claude mcp add --scope user sap-webgui -e CDP_URL=http://localhost:9223 '--' <command>.

  • Claude Code .mcp.json and Claude Desktop: put it in the env object, for example "env": { "CDP_URL": "http://localhost:9223" }.

  • opencode: put it in the environment object.

  • Any client: a .env file in the working directory of the server process is read too, but that directory depends on how your client starts the server, so prefer the client config.

NOTE

GITHUB_PAT is optional - only needed for log_feedback (creates GitHub issues) and abapGit operations with private repositories.

Step 5: Verify the setup

Before your first prompt, check that the MCP server starts correctly. Open a terminal (PowerShell on Windows, Terminal on macOS/Linux) and run:

Claude Code:

claude mcp list

Expected output:

sap-webgui: C:/path/to/sapwebgui_mcp_windows_<version>.exe ✓ Connected

opencode:

opencode mcp list

Expected output:

● ✓ sap-webgui connected

If you see ✗ Failed, the most common cause is a wrong path to the executable in your config. Double-check the path and that the file exists there. Run opencode mcp debug sap-webgui for more detail.

For Claude Code with a user-scope registration there is no config file to edit: claude mcp get sap-webgui shows the registered path, and to change it (for example after downloading a new version), run claude mcp remove sap-webgui -s user and add the server again.

TIP

Getting started: Restart Claude Desktop, Claude Code, or opencode, make sure Chrome from Step 3 is running (on Windows it starts automatically if it is not), then try: "Log me into SAP", "Run transaction SE16" or "Take a screenshot of the current SAP screen". If the agent tries to start another browser tool or to install Chrome, cancel and be explicit: "log me into SAP using the sap-webgui MCP server".

Docker

Use Docker instead of steps 1 and 4 if you prefer not to install the executable or Python. Steps 2 (systems.json), 3 (start Chrome yourself) and 5 still apply. Because the server then runs in a container, it cannot reach Chrome on your host directly, so a small CDP proxy is needed.

Prerequisites: Docker Desktop, Chrome, and a VPN connection if your SAP system is on an internal network. (The Docker setup is described for Docker Desktop on Windows and macOS.) Verify Docker is running:

docker --version

1. Start Chrome with remote debugging as in Step 3. In Docker the server cannot auto-launch Chrome, so you must do this yourself.

2. Set up the CDP proxy. Chrome rejects CDP connections whose Host header is not localhost, and a container reaches your host as host.docker.internal. The proxy rewrites the header. Create a folder (e.g., C:\sap-mcp\) and add these two files:

docker-compose.yml

services:
    cdp-proxy:
        image: nginx:alpine
        ports:
            - '9223:9222'
        volumes:
            - ./nginx-cdp-proxy.conf:/etc/nginx/conf.d/default.conf:ro
        restart: unless-stopped

networks:
    default:
        name: sap-mcp-network

nginx-cdp-proxy.conf

server {
    listen 9222;

    resolver 127.0.0.11 valid=30s;

    location / {
        set $backend "host.docker.internal:9222";
        proxy_pass http://$backend;
        proxy_set_header Host localhost;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;

        sub_filter 'ws://localhost/' 'ws://host.docker.internal:9223/';
        sub_filter 'ws://localhost:9222/' 'ws://host.docker.internal:9223/';
        sub_filter_once off;
        sub_filter_types application/json;
    }
}

Then start the proxy:

cd C:\sap-mcp
docker compose up -d

Verify it's running:

docker ps --filter "name=cdp-proxy" --format "table {{.Names}}\t{{.Status}}"

3. Register the container with your MCP client. The image is ghcr.io/hochfrequenz/sapwebgui.mcp:latest. systems.json is mounted into the container. Replace:

  • C:/Users/YourName with your home folder (on macOS, use /Users/YourName/...). Docker treats a mount source that is not an absolute path as the name of a Docker volume, so ~ does not work here.

  • your_github_pat with a GitHub Personal Access Token, or remove the GITHUB_PAT lines if you do not need that feature (see the note under Optional environment variables).

Claude Desktop (claude_desktop_config.json, see Claude Desktop for its location):

{
    "mcpServers": {
        "sap-webgui": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--network",
                "sap-mcp-network",
                "-e",
                "BROWSER_MODE=connect",
                "-e",
                "CDP_URL=http://cdp-proxy:9222",
                "-v",
                "C:/Users/YourName/.config/sap-mcp/systems.json:/home/appuser/.config/sap-mcp/systems.json:ro",
                "-e",
                "GITHUB_PAT=your_github_pat",
                "ghcr.io/hochfrequenz/sapwebgui.mcp:latest"
            ]
        }
    }
}

Claude Code (user scope, run once):

claude mcp add --scope user sap-webgui '--' docker run -i --rm --network sap-mcp-network -e BROWSER_MODE=connect -e CDP_URL=http://cdp-proxy:9222 -v C:/Users/YourName/.config/sap-mcp/systems.json:/home/appuser/.config/sap-mcp/systems.json:ro -e GITHUB_PAT=your_github_pat ghcr.io/hochfrequenz/sapwebgui.mcp:latest

Everything after '--' is the Docker command and is passed through unchanged, so the -e flags there are Docker's, not Claude Code's. Keep the quotes around '--' (in cmd.exe, write a plain --; see Claude Code for why). Write the home folder path out in full instead of using ~, because how ~ is expanded on the command line depends on the shell. A GITHUB_PAT typed on the command line ends up in your shell history. For a per-project registration, use the same command and args in .mcp.json; for opencode use "command": ["docker", "run", ...] with the same arguments.

If Docker Desktop isn't running, or the image was never pulled, you might get a nonspecific error "1 MCP server failed · /mcp". Try pulling manually (and see Docker image pull fails):

docker pull ghcr.io/hochfrequenz/sapwebgui.mcp:latest

If the containers started but Chrome is missing, the agent will likely understand how to log in but fail on the first tool call.

Related MCP server: winagent

Capabilities

Your AI client automatically discovers all individual tools and their schemas upon connection. At a high level, the server gives your agent:

  • Drive Any SAP Transaction — Execute transaction codes (sap_transaction), fill form fields (sap_fill_form, sap_set_field, checkboxes, radio buttons, dropdowns), click buttons, press keys, select tabs, read and interact with ALV grids and tables, and handle modal popups and status bar messages.

  • Transaction Shortcuts — Built-in tools for common developer and basis tasks: query tables (SE16/SE16N), inspect transports (SE09), search background jobs (SM37), inspect short dumps (ST22), query application logs (SLG1), read table maintenance views (SM30), look up Data Dictionary objects (SE11), classes (SE24), function modules (SE37) and transactions (SE93), and search the IMG (SPRO). sap_quick_report runs a report in one call: it enters the transaction, fills the selection screen, presses Execute and reads the result.

  • Editing ABAP in SAP — sap_se38_edit, sap_se37_edit and sap_se24_edit change existing reports, function modules and class methods in place. Prefer abapGit or an ADT MCP where you can.

  • Visual Validation & Screenshots — sap_screenshot captures any SAP screen for documentation, E2E test verification, or human-in-the-loop inspection.

  • Offline Catalogs — search_transactions, search_tables, search_classes and search_function_modules search without an active SAP connection.

  • abapGit & Source Code — Pull abapGit repositories (sap_abapgit_pull, sap_abapgit_list_repos) and read ABAP report source code (sap_read_se38_source). Pulls use the Z_ABAPGIT_PULL_MCP_SHORTCUT report on the SAP system. For private repositories, set GITHUB_PAT or ABAPGIT_PAT. sap_abapgit_pull takes an optional branch (e.g. main, feature/x): it switches the registered repository to that branch persistently (kept only if the pull succeeds) and clears a commit pin; the result's branch and sap_abapgit_list_repos show where the repository is. Instead of repo, sap_abapgit_pull accepts key (the 12-digit repository key from sap_abapgit_list_repos), the only unique identifier when two repositories share a name or URL; it needs a report version with P_KEY.

  • Multi-Session Management — Every SAP session is a browser tab. List, bind, release, close, and reset parallel sessions across concurrent agent tasks (sap_session_list, sap_session_bind, sap_session_release, sap_session_close, sap_session_reset_to_primary). sap_session_detach exists but is not supported (it always returns an error): use sap_session_close.

  • Browser Automation — Low-level browser actions (browser_click, browser_fill, browser_keyboard, browser_snapshot, browser_screenshot, browser_evaluate, ...) are available as escape hatches for pixel-level control.

  • Prompts — Ready-made workflows the client can offer: create_business_partner, explore_table, explore_class, explore_function_module, se16_bulk_read and abapgit_workflow.

Configuration Reference

SAP Credentials (via systems.json)

SAP credentials (user, password, client, language, host) are configured in systems.json (or systems.yaml), not via server environment variables. See sap-mcp-config for the file format. Override the config file path with SAP_CONFIG_FILE. The language of each system must be DE, EN or IT (case-insensitive; omitted means EN) - these are the languages this server supports, and any other value, such as FR, is rejected when the config is loaded with language must be one of "DE", "EN", "IT". The variables SAP_USER, SAP_PASSWORD, SAP_MANDANT, SAP_LANGUAGE, SAP_CONNECTION_NAME and SAP_CREDENTIALS that some older MCP setups used are ignored by the server and can be removed from existing configs (SAP_LANGUAGE is read by the integration tests only).

Individual fields may still be sourced from the environment with an ${env:VAR} placeholder - e.g. "password": "${env:SAP_DEV_PASSWORD}" - which keeps secrets out of the file while the structure stays in it. Placeholders work in host, client, user, password, language, oauth2_client_id and the top-level default_system.

An unset or empty variable makes the config invalid, so the first tool call that needs a credential - sap_login, for instance - fails with an error naming the variable, never a silently empty credential. Note that the server itself still starts: config loading is lazy, so the failure surfaces on first use rather than at launch. Tools that only list configuration, such as sap_list_connections, do not fail on an invalid config but report the reason in a config_error field of their result instead of returning a silently empty list; the server instructions carry the same message. Text that only looks like a placeholder is used verbatim, so a typo such as ${SAP_PASSWORD} (missing the env: prefix) becomes your literal password rather than an error - see the placeholder rules for the exact forms.

OS

Default path

Windows

%USERPROFILE%\.config\sap-mcp\systems.json

macOS/Linux

~/.config/sap-mcp/systems.json

Environment Variables (server-specific)

All of these are optional. The server reads them from its process environment and from a .env file in its working directory.

Variable

Required

Description

Default

SAP_URL

No

Fallback WebGUI URL, used only when the selected system has no host in systems.json (the URL is normally derived from host)

""

SAP_CONFIG_FILE

No

Path to systems.json (see table above for default per OS)

(see above)

OUTPUT_DIR

No

Directory that output_file tool arguments (e.g. sap_se16_query) are sandboxed to. Set this when the server's cwd isn't your project directory.

"" (current working directory)

BROWSER_MODE

No

connect (existing Chrome) or launch (Playwright starts a browser; needs playwright install, not available in the executable)

connect

BROWSER_TYPE

No

chromium, firefox, or webkit

chromium

BROWSER_HEADLESS

No

Run the browser in headless mode (applies to BROWSER_MODE=launch)

false

CDP_URL

When BROWSER_MODE=connect

Chrome DevTools Protocol URL

http://localhost:9222

CHROME_PATH

No

Windows only: explicit path to the Chrome binary for auto-launch. Ignored on macOS and Linux.

"" (auto-detect)

CHROME_USER_DATA_DIR

No

Windows only: user data directory for auto-launched Chrome

<tempdir>/chrome-debug

GITHUB_PAT

No

GitHub PAT for log_feedback issues and abapGit auth

-

GITHUB_USER

No

GitHub username for abapGit (falls back to x-access-token)

-

GITHUB_REPO

No

Repository for feedback issues

Hochfrequenz/sapwebgui.mcp

ABAPGIT_PAT

No

Separate PAT for abapGit (overrides GITHUB_PAT if set)

-

LOG_FORMAT

No

Set to json for JSON log output

"" (human-readable)

LOG_LEVEL

No

DEBUG, INFO, WARNING, or ERROR

INFO

Legacy BACKEND_TYPE setting

Earlier versions of the combined project selected their backend with BACKEND_TYPE. This server has only the Web GUI backend and does not read that variable. Only one value is noticed, to help users who still have an old configuration: if BACKEND_TYPE is desktop (case-insensitive, key and value; set in the process environment or in a .env file in the working directory, where the environment wins), the server writes a warning to its log at startup and appends a notice to the server instructions that points the agent to sapgui.mcp. The server still starts and works as a Web GUI server. Any other value is ignored silently. Remove the variable from your configuration.

Logging

The server logs to stderr by default using a structured text format (stdout carries the MCP protocol). Set LOG_FORMAT=json for machine-readable JSON output and LOG_LEVEL to change the level.

The release binaries (see Step 1) honour user overrides via .env or environment variables.

Troubleshooting

Finding your Chrome path

The Chrome startup commands in this guide use C:\Program Files\Google\Chrome\Application\chrome.exe - the default path for a system-wide Chrome installation. If you get an error like "The system cannot find the path specified", Chrome is likely installed in a different location.

Common Chrome paths on Windows:

Installation type

Path

System-wide (all users)

C:\Program Files\Google\Chrome\Application\chrome.exe

Per-user (current user)

C:\Users\<YourName>\AppData\Local\Google\Chrome\Application\chrome.exe

How to find your Chrome path (step by step):

  1. Find your Chrome shortcut (on your desktop or in the Start menu)

  2. Right-click the Chrome shortcut → click Properties

  3. In the Properties window, look at the Target field

  4. Copy the path from that field (everything before any -- flags)

For example, if the Target field shows:

"C:\Users\JaneDoe\AppData\Local\Google\Chrome\Application\chrome.exe"

Then your Chrome startup command is:

& "C:\Users\JaneDoe\AppData\Local\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\temp\chrome-debug" --ignore-certificate-errors

Quick check in PowerShell - this command finds Chrome automatically:

Get-Item "C:\Program Files\Google\Chrome\Application\chrome.exe","$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe" -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName

To let the server find Chrome (when it auto-launches it), set CHROME_PATH to that path.

Chrome connection errors

  1. Make sure Chrome is running with --remote-debugging-port=9222

  2. Make sure you used --user-data-dir (required, otherwise Chrome joins the existing instance)

  3. Verify with: Invoke-WebRequest -Uri 'http://localhost:9222/json/version' -UseBasicParsing (macOS/Linux: curl http://localhost:9222/json/version)

  4. On macOS and Linux the server cannot start Chrome for you: start it yourself (Step 3). An error that asks you to set CHROME_PATH means Chrome is not reachable on port 9222; CHROME_PATH does not help there.

SAP login fails

  • Check that the system's host in systems.json (or SAP_URL) is correct and that {host}/sap/bc/gui/sap/its/webgui opens in your browser

  • Verify user, password and client in systems.json (see Configuration Reference)

  • Try logging in manually first to verify credentials

Claude Code ignores the global registration

When the same server name is registered in more than one scope, Claude Code uses the entry with the highest precedence: local (stored per project in ~/.claude.json), then project (.mcp.json), then user (the global registration from claude mcp add --scope user). See MCP installation scopes in the Claude Code documentation. A forgotten registration with the same name therefore shadows a correct global one. If it points at a binary that no longer exists, the server fails to connect (for example with CONNECTION_CLOSED).

To find and remove the stale entry:

  • Run claude mcp get sap-webgui from the project directory. The Scope: line shows which registration Claude Code actually uses.

  • Remove a local-scope entry with claude mcp remove sap-webgui -s local, or the entry in the project's .mcp.json with claude mcp remove sap-webgui -s project. Always pass -s: without it, remove deletes the server from whichever scope it finds it in, which may be your global registration. (The -s project variant edits the project's possibly shared .mcp.json, so commit that change only if the whole team should lose the entry.)

When cleaning up configs from older setups, you can also drop the old SAP_* credential variables and BACKEND_TYPE from any env block. Credentials are configured only via systems.json (optionally with ${env:VAR} placeholders). SAP_URL and SAP_CONFIG_FILE are still supported.

Transaction input field (OK-Code field) not visible

On first use of SAP Web GUI, the transaction input field (called "OK-Code field" in SAP) may be hidden. The MCP server tries to enable it automatically, but if that fails, you can enable it manually:

  1. Click the gear icon in the toolbar ("GUI-Aktionen und -Einstellungen" / "GUI Actions and Settings")

  2. Select "Einstellungen..." / "Settings..."

  3. Enable "OK-Code-Feld anzeigen" (Show OK-Code Field)

SAP Web GUI Settings - Enable OK-Code Field

This is a one-time setting that is saved for subsequent logins.

Tools timeout or hang

SAP Web GUI can be slow. If operations timeout:

  1. Check the Chrome window - is SAP responding?

  2. Try sap_keepalive_start to prevent session timeouts

  3. In Docker setups, check the container logs: docker logs <container-id>

"network sap-mcp-network not found"

Docker setups only: the CDP proxy isn't running or was never started. Start it:

cd C:\sap-mcp
docker compose up -d

"Cannot connect to CDP proxy"

Docker setups only. Check if the proxy is running:

docker ps | Select-String cdp-proxy

Check proxy logs:

docker logs sap-mcp-cdp-proxy-1

"Port 9223 already in use"

Docker setups only: another service is using port 9223. Stop it or change the port in docker-compose.yml:

ports:
    - '9224:9222' # Use 9224 instead

Docker image pull fails

The image is public, so docker pull needs no login:

docker pull ghcr.io/hochfrequenz/sapwebgui.mcp:latest
  • "denied" or "unauthorized": an old or expired login to ghcr.io is still stored. Run docker logout ghcr.io and pull again.

  • "manifest unknown": the tag does not exist. Image tags have no v prefix: use 0.20.1, not v0.20.1, or latest.

  • "failed to connect to the docker API": Docker Desktop is not running. Start it and pull again.

Architecture

The server drives SAP Web GUI in Chrome through Playwright and the Chrome DevTools Protocol:

graph BT
    Claude["Claude Desktop / Claude Code / opencode"]
    MCP["MCP Server (sapwebguimcp)\nPlaywright for browser automation\nSAP-specific tools"]
    CDP["CDP Proxy (nginx)\nOnly needed for Docker"]
    Chrome["Chrome\nSAP Web GUI loaded\nPersistent session"]

    Claude -- "MCP (stdio)" --> MCP
    MCP -- "HTTP / WebSocket" --> CDP
    CDP -- "CDP (Chrome DevTools Protocol)" --> Chrome

Without Docker the server connects to Chrome directly and the proxy is not needed.

This server is part of a small ecosystem of SAP + AI tooling:

  • sapgui.mcp - the sibling project for SAP GUI for Windows (COM scripting). Use it if you work with SAP GUI instead of the browser.

  • aibap.mcp - complementary MCP server that talks to SAP via the ADT REST API (read/write source, activate, syntax-check, run unit tests, manage transports). Where sapwebgui.mcp drives SAP through its UI, aibap.mcp talks directly to the ABAP Development Tools HTTP API. The two are designed to coexist and share ~/.config/sap-mcp/systems.json.

  • AIBAP_TEMPLATE_REPOSITORY - GitHub template for AI-driven ABAP vibe-coding projects. Documents the two-agent pattern (dev via aibap.mcp, test / documentation / screenshots via a GUI MCP such as this one) end-to-end.

  • Z_ABAPGIT_PULL_MCP_SHORTCUT - SAP-side ABAP report that sap_abapgit_pull calls to pull abapGit repos through the ABAP API. Install it on any SAP system where you want the abapGit pull tools to work.

  • sap-mcp-config - shared config schema for systems.json, consumed by this server (Python), sapgui.mcp (Python) and aibap.mcp (Go).

Contributing

See CONTRIBUTING.md for the development setup, tests and code style, and ARCHITECTURE.md for the code structure.

Available Tools

71 tools
browser_clickBrowser ClickB

Click an element by CSS selector. BEFORE clicking buttons, use sap_get_shortcuts to check if a keyboard shortcut is available - shortcuts are faster and more reliable than clicks.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: selector (required), session, agent_id. Returns: Result from browser_click tool.

browser_evaluateBrowser EvaluateA

Execute JavaScript in the browser. Use with caution - this has full access to the page context. Prefer SAP-specific tools when available. Returns: JSON-serialized result.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: script (required), session, agent_id. Returns: Result from browser_evaluate tool.

browser_fillBrowser FillA

Fill a single input field by CSS selector. For filling multiple fields on the same screen, use sap_fill_form instead - it fills all fields in a single call, which is much faster.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: value (required), selector (required), session, agent_id. Returns: Result from browser_fill tool.

browser_get_htmlBrowser Get HtmlA

Get HTML content of an element or the full page. For large HTML (>50KB), returns a File to avoid context bloat. Prefer sap_get_screen_text or sap_get_form_fields for structured SAP data. Args: selector = CSS selector (None for full page), outer = include element itself (outerHTML) or just children (innerHTML).

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: outer, session, agent_id, selector.

browser_keyboardBrowser KeyboardA

Send keyboard input (key press or text typing). Important: For SAP shortcuts like Ctrl+S, prefer sap_press_key which auto-reads the status bar! For filling multiple form fields, use sap_fill_form - much faster. Args: key = key to press (e.g., 'Enter', 'Tab', 'F3'), text = text to type character by character.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: key, text, session, agent_id. Returns: Result from browser_keyboard tool.

browser_navigateBrowser NavigateA

Navigate to a URL. For SAP login, use sap_login instead - it handles credentials and session setup.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: url (required), session, agent_id. Returns: Result from browser_navigate tool.

browser_screenshotBrowser ScreenshotA

⚠️ WRONG TOOL — use browser_snapshot instead. browser_snapshot returns a compact text-based accessibility tree that is sufficient for 95% of use cases.

ONLY use browser_screenshot when:

  1. The user EXPLICITLY asks for a screenshot

  2. You need to verify visual rendering/layout issues that cannot be diagnosed from the accessibility tree

This tool returns a large image that rapidly fills up conversation context and degrades performance.

Args: full_page = capture entire scrollable page, selector = optional CSS selector to capture specific element.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id, selector, full_page.

browser_select_optionBrowser Select OptionA

Select an option from a dropdown/select element. For SAP dropdowns, prefer sap_fill_form or sap_set_field which handle SAP-specific dropdown behavior. Args: selector = CSS selector for select element, value = option value to select, label = option text (alternative to value).

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: selector (required), label, value, session, +1 more. Returns: Result from browser_select_option tool.

browser_snapshotBrowser SnapshotA

Get accessibility tree snapshot of the current page. Returns a YAML representation of the ARIA tree - useful for understanding page structure when other tools fail. Args: selector = optional CSS selector to scope the snapshot.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id, selector. Returns: Result from browser_snapshot tool.

browser_waitBrowser WaitA

Wait for an element to reach a specific state. IMPORTANT: Only useful with a selector - calling without a selector is pointless because MCP round-trip time already provides natural delays. Good uses: wait for element to appear (state='visible') or loading spinner to disappear (state='hidden'). Args: selector = CSS selector to wait for, timeout = max wait in ms, state = 'visible'/'hidden'/'attached'/'detached'.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: state, session, timeout, agent_id, +1 more. Returns: Result from browser_wait tool.

chooseChooseA

Present the user with a set of options to choose from.

Call this tool when you need the user to make a decision between discrete alternatives. Use it proactively — don't ask the user to type their choice in chat when you can present clean, clickable options instead.

The user will see a card with one button per option. When they click one, their choice appears as a message in the conversation (as if the user typed it), like:

"Which deployment strategy?" — I selected: Blue-green

IMPORTANT: After calling this tool, you MUST stop and wait for the user's response. Do not continue or take any other actions until you see the "I selected:" message.

Inputs: prompt (required), options (required), title.

log_feedbackLog FeedbackA

Log technical feedback about tool usage patterns, friction points, or optimization opportunities. ENCOURAGED whenever you notice something that could improve tooling. If GITHUB_PAT configured, auto-posts as GitHub issue. BE DETAILED: include transaction code, steps to reproduce, tool names, selectors, timing observations, what you tried, error messages. TAGS: 'tool-combination' (tools always used together), 'repetition' (same tool repeated), 'selector' (hard to find), 'timing' (slow/timeout), 'workflow' (could be simplified), 'missing-tool', 'error-handling', 'deadlock' (got stuck), 'problem' (blocked progress). Use markdown formatting: backticks for code, bold for emphasis.

Inputs: feedback (required), tags. Returns: Result from log_feedback tool.

log_intentLog IntentA

MANDATORY: Log intent when using SAP. You MUST call this at the start of every SAP task and before any SAP write operation. Required for compliance and accountability. WHEN TO CALL: (1) ALWAYS at the start of every SAP-related user request, (2) ALWAYS before any SAP write operation (create, update, delete, post), (3) At milestones during multi-step workflows (e.g., 'Order 3 of 10'), (4) Before running transactions that modify data. Args: intent = high-level description (e.g., 'User requested to create sales order'), context = optional dict (e.g., {'tcode': 'VA01', 'customer': '12345'}).

Inputs: intent (required), context. Returns: Result from log_intent tool.

sap_abapgit_list_reposabapGit List RepositoriesA
Read-onlyIdempotent

List registered abapGit repositories with their metadata. Returns repo names, Git URLs, packages, branches, last pull timestamps and (when the report provides it) the repository key, plus total_count and matched_count. Use name/package/url/key to filter instead of listing everything (a system can have hundreds of repositories): name, package and url are case-insensitive substrings, or globs when they contain * or ?; key is an exact match, digits, zero-padded to 12; all given filters must match. compact=True returns only name, package and key. Use this to discover the correct repo name before calling sap_abapgit_pull.

Inputs: key, url, name, compact, +3 more. Returns: Result of listing registered abapGit repositories.

sap_abapgit_pullabapGit PullA
DestructiveIdempotent

Pull changes from a remote git repository using abapGit API. WARNING: overwrites local ABAP objects. Select the repository by repo (name/URL) or by key (from sap_abapgit_list_repos), not both. If a transport is required the error says so: retry with trkorr=... If 'status unknown', the pull may have run: check the last pull time before retrying. Optional branch switches the repository to that branch persistently (kept only if the pull succeeds) and clears a commit pin.

Inputs: key, pat, repo, branch, +4 more. Returns: Result for abapGit actions (pull, stage, diff, check). Use factory methods for…

sap_breakpoint_deleteSap Breakpoint DeleteA

Delete an external ABAP breakpoint on a specific line of a program, class method, or function module. Desktop backend only.

Provide either line_number (1-indexed SAP display line) or match_pattern (substring or regex matched against source lines).

If the line has no breakpoint, SAP sets one. This tool detects that and re-applies to undo it, then reports action='was_not_set'.

Note: this only removes the breakpoint from the source editor. It does NOT step or continue a debugger that is currently stopped and showing a modal dialog — there is no tool for that; only a human at the SAP GUI can dismiss it.

Inputs: object_name (required), object_type (required), session, agent_id, +3 more. Returns: Result of sap_breakpoint_delete.

sap_breakpoint_listSap Breakpoint ListA
Read-onlyIdempotent

List all external ABAP breakpoints for the current user on a program, class method, or function module. Desktop backend only.

Opens 'Hilfsmittel > Breakpoints > Anzeigen...' dialog in the source editor, reads the grid, and returns matching breakpoints.

Note: if this session is currently stopped at a breakpoint, this tool fails with an error naming the ABAP debugger instead of opening the dialog — continue or exit the debugger in SAP GUI first.

Inputs: object_name (required), object_type (required), session, agent_id, +1 more. Returns: Result of sap_breakpoint_list.

sap_breakpoint_setSap Breakpoint SetA
Destructive

HIGHLY DANGEROUS — DO NOT CALL unless a human user has explicitly asked for a breakpoint to be set. Live-verified (issue #791): once the breakpoint fires, the SAP session stops and SAP GUI opens the ABAP debugger. The call that triggered it and every later call on that session fail after a few seconds with an error naming the debugger, as can slow calls on other sessions of the same SAP connection; sessions of other connections are not affected. The session works again once a human continues or exits the debugger in SAP GUI.

Set an external ABAP breakpoint on a specific line of a program, class method, or function module. Desktop backend only — WebGUI does not support external breakpoints.

Provide either line_number (1-indexed SAP display line) or match_pattern (substring or regex matched against source lines).

SAP toggles breakpoints: if the line already has a breakpoint, VKey 45 deletes it. This tool only sets the breakpoint — it does not run anything.

IMPORTANT — before calling this tool, ask the human operator for explicit permission and explain the consequences: there is NO tool to step, continue, or read variables in the resulting debugger. If the breakpoint later fires during a GUI run, SAP GUI opens a modal interactive ABAP debugger that only a human can drive — the agent cannot see or control it, and it may fire once per row/iteration if the code path repeats. The halted session is unusable for the agent until then, as described above. Only proceed once the human has confirmed they intend to sit at the SAP GUI and step through the debugger themselves; do not use this to silently 'verify a code path is reached' from an unattended flow.

Inputs: object_name (required), object_type (required), session, agent_id, +3 more. Returns: Result of sap_breakpoint_set.

sap_click_buttonSap Click ButtonA

Click a button on the current SAP screen by its label text.

Use sap_discover_buttons first to see available buttons. Prefer sap_press_key with keyboard shortcuts (F-keys, Ctrl+*) when available — they are faster and more reliable. Use this tool when no shortcut exists.

Args:

  • label: Button label text (e.g., 'Execute', 'Save', 'Ausführen')

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: label (required), session, agent_id. Returns: Result from sap_click_button tool.

sap_click_table_cellSap Click Table CellA

Click a cell in an ALV grid table. Automatically targets the correct clickable element (hotspot span vs TD). Use after sap_read_table to navigate to detail views.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: row (required), column (required), action, session, +1 more. Returns: Result from sap_click_table_cell tool.

sap_close_popupSap Close PopupA

Close an active popup dialog by clicking a button. Use when active_window shows 'wnd[1]' or higher and you want to dismiss the dialog. Note: Not all popups need closing - if the popup is a form you need to fill, use sap_discover_fields and sap_fill_form instead (they automatically target the active window). Specify button by label ('Ja', 'Nein') or accesskey ('J', 'N'), or use close=True to click the X button if available.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: close, button, session, agent_id. Returns: Result from sap_close_popup tool.

sap_discover_buttonsSap Discover ButtonsA

Discover clickable buttons on the current SAP screen. Returns buttons with label, selector/ID, shortcut (e.g. F3), and accesskey. Prefer keyboard shortcuts (sap_press_key) when available — they're faster and more reliable. To press a discovered button: use browser_click(selector) on WebGUI, or sap_com_evaluate(element_id, action='call', method='Press') on Desktop. For input fields use sap_discover_fields instead.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id. Returns: Result from sap_discover_buttons tool.

sap_discover_fieldsSap Discover FieldsA

Discover input fields on the current SAP screen (or active popup dialog). Returns fields with label, name, value, and a selector/ID for targeting the field. Automatically targets the active window — if a popup is open, shows popup fields. Use the label with sap_fill_form or sap_set_field to fill fields (works on both backends). The 'selector' field is a CSS selector on WebGUI or a SAP GUI element ID on Desktop. For buttons, use sap_discover_buttons instead.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id. Returns: Result from sap_discover_fields tool.

sap_fill_formSap Fill FormA

Fill multiple SAP form fields in a single call. Use this when filling 2+ fields on the SAME screen without UI navigation between them.

Keys can be:

  • Visible label text (e.g., 'First Name', 'Straße') — works on both backends

  • CSS selectors starting with '#' (WebGUI, e.g., '#M0:46:1:1::0:21')

  • SAP GUI element names (Desktop, e.g., 'BUT000-NAME_LAST')

When to use:

  • Filling a form with multiple input fields

  • All fields visible on current screen

  • No button clicks or navigation needed between fields

When NOT to use:

  • Single field only (use sap_set_field)

  • Fields on different screens/tabs

  • Need to click buttons between fills

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Example payload: {"fields": {"Vorname": "Mario", "Nachname": "Rossi"}, "strict": false}

Inputs: fields (required), strict, session, agent_id. Returns: Result from sap_fill_form tool.

sap_get_capabilitiesSap Get CapabilitiesA

RECOMMENDED: Call at the start of every SAP session. Returns all available tools with their full descriptions. Reading this first helps you understand what capabilities are available, work faster, and avoid common mistakes like clicking buttons when keyboard shortcuts are available.

Inputs: no named parameters. Returns: Result from sap_get_capabilities tool.

sap_get_form_fieldsSap Get Form FieldsA

Discover fillable form fields on the current SAP screen (or active popup dialog). Returns field IDs, labels, types (text/dropdown/checkbox/radio), and current values. Automatically targets the active window — if a popup is open, shows popup fields. Use include_dropdown_options=True to also fetch available options for dropdown fields.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id, include_dropdown_options. Returns: Result from sap_get_form_fields tool.

sap_get_screen_infoSap Get Screen InfoB

Get technical information about the current SAP screen

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id. Returns: Result from sap_get_screen_info tool.

sap_get_screen_textSap Get Screen TextA

Get all readable text from the current SAP screen. Use include_dropdown_options=True to also fetch available options for dropdown fields.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id, include_dropdown_options. Returns: Result from sap_get_screen_text tool. Extracts all readable text from the curre…

sap_get_shortcutsSap Get ShortcutsA

Discover keyboard shortcuts available on the current SAP screen. Use BEFORE clicking buttons - shortcuts like F5, Ctrl+S are faster and more reliable. Returns action text and key combination for each available shortcut.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id. Returns: Result from sap_get_shortcuts tool.

sap_keepalive_startSap Keepalive StartB

Start a background task that keeps the SAP session alive

Inputs: session, agent_id, interval_seconds. Returns: Result from sap_keepalive_start/stop tools.

sap_keepalive_stopSap Keepalive StopC

Stop the background keepalive task

Inputs: session, agent_id. Returns: Result from sap_keepalive_start/stop tools.

sap_list_connectionsSap List ConnectionsA

List available SAP systems. Returns two sections: 'configured_systems' from systems.json (pass the 'key' field as system_key to sap_login), and 'connections' from SAP Logon (SAPUILandscape.xml, Desktop only). IMPORTANT: pass a configured_systems 'key' as system_key to sap_login, NOT a SAP Logon entry name. If configured_systems is empty, check config_error.

Inputs: no named parameters. Returns: Result from sap_list_connections tool.

sap_loginSap LoginA

Log into SAP. On WebGUI: requires Chrome with --remote-debugging-port=9222 and VPN (if internal SAP). On Desktop: opens a NEW parallel session each call — re-login does NOT replace prior logins. You can be logged into the same SAP Logon entry as multiple distinct (client, user) tuples concurrently. The returned LoginResult.session_id is the registry ID ('s1', 's2', ...) you pass on subsequent tool calls to address THIS specific login. Concurrency note: sessions on one connection share one single-threaded COM engine; parallel scripting loops on that connection run sequentially (no speedup). For bulk work on one connection, prefer one large loop in a single script. Parallelism helps only across separate connections/systems. Use sap_session_list to see all currently active sessions. Credentials are read from ~/.config/sap-mcp/systems.json. Use system_key (dictionary key from systems.json) to select a non-default system. Call sap_list_connections first to see available system keys.

Inputs: url, client, system_key. Returns: Result from sap_login tool.

sap_lookup_fieldsSap Lookup FieldsA

Look up known field CSS selectors for an SAP transaction (WebGUI only). Returns pre-discovered selectors from a static registry. On Desktop, use sap_discover_fields instead — it discovers fields dynamically.

Inputs: transaction (required). Returns: Result from sap_lookup_fields tool.

sap_press_keySap Press KeyA

Send a keyboard shortcut to SAP

Note on 'Escape': on the desktop backend it sends SAP VKey 12 (F12 / Cancel), not the Windows Esc key; its meaning is screen dependent (some editor screens open an 'Exit editor' dialog). On the WebGUI backend the key is passed to the browser as a normal key press (no VKey mapping). To dismiss a popup use sap_close_popup.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: key (required), session, agent_id. Returns: Result from sap_press_key tool. For shortcut keys (F-keys or Ctrl+*), the statu…

sap_quick_reportSap Quick ReportA

Execute a transaction, fill the selection screen (fields, checkboxes, radio buttons), press Execute (F8), and return the result — all in one call.

Works with any SAP report/list transaction that has a selection screen (VA05, ME2M, MB51, FBL1N, Z-transactions, etc.).

After execution, you remain on the result screen. If the result is 'unknown', use individual tools to investigate further.

If you already know a transaction shows a popup after F8 (e.g., a variant selection dialog), pass post_f8_keys=['Enter'] to dismiss it automatically.

Do NOT use for:

  • SE16 (use sap_se16_query instead)

  • SM37 (use sap_sm37_lookup instead — has job log support)

  • Transactions without selection screens (e.g., BP, VA01)

  • SE11/SE24/SE37 (use dedicated lookup tools)

WebGUI-only. Returns an error on desktop backend.

Inputs: tcode (required), fields, radios, session, +5 more. Returns: Result of sap_quick_report.

sap_read_se38_sourceRead SE38 SourceA
Read-onlyIdempotent

Read ABAP report source code from SE38. If sap-adt is available, prefer its get_source tool. Navigates to SE38, enters the program name, and displays the source code. Useful for verifying abapGit pull operations.

Inputs: program_name (required), session, agent_id. Returns: object

sap_read_status_barSap Read Status BarA

Read the current message from SAP's status bar

Also returns message_id / message_number (desktop only), which identify the message independently of the logon language, plus message_parameters (its &1-&4 runtime values, which may themselves be translated).

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: session, agent_id. Returns: Result from sap_read_status_bar tool.

sap_read_tableSap Read TableA

Read data from an ALV grid or table on the current screen

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: end_row, session, agent_id, max_rows, +1 more. Returns: Result from sap_read_table tool. For ALV grids, includes grid-level metadata wi…

sap_screenshotSap ScreenshotA
Read-only

Take a screenshot of the current SAP screen.

Returns a PNG screenshot as an image. Works on both WebGUI and Desktop backends. ⚠️ Screenshots consume significant context tokens. Prefer sap_get_screen_text or sap_get_form_fields for reading screen content. Use screenshots only for visual debugging or when the user explicitly requests one.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: session, agent_id.

sap_se09_lookupSap Se09 LookupA
Read-only

Look up transport requests from SE09 (Transport Organizer). If sap-adt is available, prefer its get_transport_requests for listing transports. USE THIS for transport release on ECC (ADT release silently fails on ECC) or when ADT is unavailable. Returns transport requests with owner, description, status, type, and target system. By default shows only modifiable requests for the current user. Supports filtering by username, request type (workbench/customizing), and status (modifiable/released/all).

Inputs: status, session, agent_id, username, +3 more. Returns: Result of SE09 transport lookup.

sap_se11_lookupSap Se11 LookupA
Read-only

Look up table or structure metadata from SE11 (ABAP Dictionary). If sap-adt is available, prefer its get_table_fields or get_object_info tools. USE THIS instead of sap_transaction('SE11') - faster and returns structured data. Returns field names, data types, lengths, and descriptions. Supports single name or list of names. Always queries live from SAP. Use object_type='table' for database tables, 'structure' for data structures. For large requests (>10 objects), provide output_file to write results to JSON file instead of returning inline (avoids context overflow).

Inputs: names (required), object_type (required), session, agent_id, +1 more. Returns: result

sap_se16_querySap Se16 QueryA
Read-only

Query SAP table data via SE16N (Data Browser). If sap-adt is available, prefer its run_query tool for simple queries. USE THIS for complex queries with dynamic filtering or when ADT is unavailable.

Filters: If a filter cannot be applied (e.g. the field is unknown or not offered by SE16N), the call fails before running the query; the error lists the SE16N selection fields when they could be read. On the WebGUI backend a filter goes into the row whose technical name matches, and only the first ~30 rows of the selection grid are rendered, so a field further down a wide table cannot be filtered (the error says so).

Performance: ~7 rows/second due to pagination.

  • 100 rows: ~14 seconds

  • 500 rows: ~1.5 minutes

  • 1000 rows: ~2.5 minutes

  • 5000 rows: ~12 minutes

For large results, use output_file to write JSON to disk and receive a summary.

Inputs: table (required), filters, session, agent_id, +2 more. Returns: result

sap_se24_editSap Se24 EditA
Destructive

Edit an existing class method in SE24 (Class Builder). If sap-adt is available, prefer its patch_source or set_source_from_file tools — faster, no GUI needed.

Replaces the method's source code, runs syntax check (Ctrl+F2), and activates (Ctrl+F3). Auto-reverts if check or activation fails.

Important: Only for EXISTING classes and methods. To create new ones, use abapGit.

Workflow: Read current class with sap_se24_lookup first to see methods, then call this tool with the full new method source.

Inputs: class_name (required), new_source (required), method_name (required), session, +1 more. Returns: Result of editing a class method in SE24.

sap_se24_lookupSap Se24 LookupA
Read-only

Look up class/interface metadata from SE24 (Class Builder). If sap-adt is available, prefer its get_source/get_class_definition tools. USE THIS instead of sap_transaction('SE24') - faster and returns structured data. Returns class structure including methods with parameters, attributes, and implemented interfaces. Supports single class or list of classes. Each method includes: name, visibility, parameters, exceptions, and description.

Inputs: classes (required), session, agent_id, output_file. Returns: result

sap_se37_editSap Se37 EditA
Destructive

Edit an existing ABAP function module in SE37. If sap-adt is available, prefer its patch_source or set_source_from_file tools — faster, no GUI needed.

Replaces the entire source code, runs syntax check (Ctrl+F2), and activates (Ctrl+F3). Auto-reverts if check or activation fails.

Important: Only for EXISTING function modules. To create new ones, use abapGit.

Workflow: Read current source with sap_se37_lookup first (check the Quelltext/Source Code tab), modify it, then call this tool with the full new source.

Inputs: new_source (required), function_module (required), session, agent_id. Returns: Result of editing a function module in SE37.

sap_se37_lookupSap Se37 LookupA
Read-only

Look up function module metadata from SE37 (Function Builder). If sap-adt is available, prefer its get_source tool for reading FM source code. USE THIS instead of sap_transaction('SE37') - faster and returns structured data. Returns function module signature including import/export/changing/tables parameters and exceptions. Supports single FM or list of FMs. Each parameter includes: name, typing (LIKE/TYPE), reference type, default value, optional flag, and description.

Inputs: function_modules (required), session, agent_id, output_file. Returns: result

sap_se38_editSap Se38 EditA
Destructive

Edit an existing ABAP report in SE38. If sap-adt is available, prefer its patch_source or set_source_from_file tools — faster, no GUI needed.

Replaces the entire source code, runs syntax check (Ctrl+F2), and activates (Ctrl+F3). Auto-reverts if check or activation fails.

Important: Only for EXISTING reports. To create new reports, use abapGit.

Workflow: Read current source with sap_read_se38_source first, modify it, then call this tool with the full new source.

Inputs: new_source (required), program_name (required), session, agent_id. Returns: Result of editing an ABAP report in SE38.

sap_se93_lookupSap Se93 LookupA
Read-only

Look up transaction metadata from SE93 (Transaction Maintenance). USE THIS instead of sap_transaction('SE93') - faster and returns structured data. Returns transaction description, program, screen/selection info, and GUI capabilities. Supports single tcode or list of tcodes. Currently supports 'dialog' and 'report' transaction types.

Inputs: tcodes (required), session, agent_id, output_file. Returns: result

sap_select_dropdownSap Select DropdownA

Select a value from a dropdown (combobox) field on the current SAP screen.

Use sap_get_form_fields(include_dropdown_options=True) first to see available dropdown fields and their options.

Unlike sap_set_field which auto-detects field type, this tool is specifically for dropdown selection and returns available_options on failure.

Args:

  • label: Dropdown field label text (e.g., 'Country', 'Language', 'Buchungskreis')

  • value: Exact option text to select from the dropdown

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: label (required), value (required), session, agent_id. Returns: Result from sap_select_dropdown tool.

sap_select_tabSap Select TabA

Select a tab on the current SAP screen by its label text.

Use sap_get_screen_text to see available tab labels on the current screen.

Args:

  • label: Tab label text (e.g., 'Address', 'Details', 'Allgemeine Daten')

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: label (required), session, agent_id. Returns: Result from sap_select_tab tool.

sap_session_bindSap Session BindA

Claim exclusive ownership of a SAP session for the calling agent. Strict by default (#643): if the session is already bound to a different agent, the call fails — pick a different session via sap_session_list, or retry with force=true to take over (use only for crash recovery, otherwise prefer leaving the existing binding intact). Re-binding the same agent is a no-op success.

Inputs: agent_id (required), session_id (required), force. Returns: Result from sap_session_bind tool.

sap_session_closeSap Session CloseA

Close a SAP session.

Closes the underlying SAP GUI session/tab and removes it from the registry. Any session ID can be closed, including "s1". With the parallel-multi-mandant contract (#671), the registry can hold multiple concurrent logins and you may legitimately want to close any of them — including the lowest-numbered one. If you close the only remaining session, the next tool call will fail with a clear "no session" error and you should call sap_login() again.

Sessions with origin "attached" (a window the user already had open) are never closed by this server: the call is refused and points at sap_session_detach.

Args: session_id: Session to close (e.g. "s1", "s2", ...)

Inputs: session_id (required). Returns: Result from sap_session_close tool.

sap_session_detachSap Session DetachA

Stop using a session WITHOUT closing it (desktop backend only).

Removes the session from the registry, drops its agent binding and stops watching its connection. No SAP GUI call is made: the SAP window stays open. This is the only way to drop an "attached" session (a window the user already had open, which sap_session_close refuses to close); it also works on sessions this server opened. The WebGUI backend has no detach; use sap_session_close there.

Args: session_id: Session to detach (e.g. "s2")

Inputs: session_id (required). Returns: Result from sap_session_detach tool.

sap_session_listSap Session ListA

List all active SAP sessions.

Returns session IDs, current transaction, screen title, client, user, and system_name for each. Use this to see what sessions exist before targeting one.

The first sap_login() registers "s1". Additional sessions come from:

  • repeated sap_login() calls (parallel multi-mandant — each new login adds a session alongside the existing ones, not replacing them — see #671)

  • sap_transaction(tcode, new_window=True) (a /o sub-session of an existing connection, sharing its login)

Desktop: when another call has been running on the connection's single COM engine for a while, the result carries a com_engine block saying which connection is busy and since when. That running call is why other tool calls on the same connection hang — wait for it instead of retrying.

Inputs: no named parameters. Returns: Result from sap_session_list tool.

sap_session_releaseSap Session ReleaseA

Release agent binding from a session. Use when an agent finishes work and wants to free the session for other agents or general use.

Inputs: session_id (required). Returns: Result from sap_session_release tool.

sap_session_reset_to_primarySap Session Reset To PrimaryA

Bulk-close every SAP session except the primary one (s1). Use this when parallel agents have left orphaned/extra windows and you want to return to a known-clean state with only s1 open. Reconciles the registry first (drops any sessions that died externally), then closes the rest. WARNING: if you call this from a non-primary session, your own session will be closed and you will appear in killed_agents — your next tool call will fail until you rebind to s1 (or another surviving session) via sap_session_bind. See issue #637 for the parallel-agent drift scenario this addresses.

Inputs: no named parameters. Returns: Result from sap_session_reset_to_primary tool. Reports the outcome of bulk-clos…

sap_session_statusSap Session StatusC

Check the current SAP session status

Inputs: session, agent_id. Returns: Result from sap_session_status tool.

sap_set_checkboxSap Set CheckboxA

Set a SAP checkbox to checked or unchecked by its label text.

Use sap_get_form_fields first to see available checkboxes and their current state.

Args:

  • label: Checkbox label text (e.g., 'Workbench-Aufträge', 'Freigegeben')

  • checked: True to check, False to uncheck

Only label lookup is supported. If the label is ambiguous or not found: on the desktop backend use sap_com_evaluate or sap_run_script and set .selected = True/False on the element by id (both are desktop-only); on the WebGUI backend use browser_evaluate.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: label (required), checked (required), session, agent_id. Returns: Result from sap_set_field tool.

sap_set_fieldSap Set FieldA

Set a single SAP form field by label, CSS selector, or element name. Finds the field dynamically and fills it with the given value.

The label parameter can be:

  • Visible label text (e.g., 'Last Name', 'Nachname') — works on both backends

  • CSS selector (WebGUI, e.g., '#M0:46:1:1::0:21')

  • SAP GUI element name (Desktop, e.g., 'BUT000-NAME_LAST')

This is simpler than sap_fill_form for single fields.

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session (for parallel agents)

Inputs: label (required), value (required), session, agent_id. Returns: Result from sap_set_field tool.

sap_set_radio_buttonSap Set Radio ButtonA

Select a SAP radio button by its label text.

Use sap_get_form_fields first to see available radio buttons and which is selected.

Args:

  • label: Radio button label text (e.g., 'Datenbanktabelle', 'Database table')

Session parameter:

  • session=None (default): Uses primary session ("s1")

  • session="s2": Targets specific session

Inputs: label (required), session, agent_id. Returns: Result from sap_set_field tool.

sap_slg1_lookupSap Slg1 LookupA
Read-only

Search and read SAP application logs from SLG1. USE THIS instead of sap_transaction('SLG1') - faster and returns structured data. Returns log entries with metadata (date, time, user, object, subobject, external ID, message count, log number). Best used when the log object is known (e.g., /SDF/CALM for Cloud ALM, /SDF/AIMAX for AI). Use '*' as object to search all logs. Requires at minimum the 'object' parameter. Returns up to 50 logs.

Inputs: object (required), session, to_date, agent_id, +4 more. Returns: result

sap_sm30_lookupSap Sm30 LookupA
Read-only

Look up SAP table maintenance view entries from SM30 (read-only display mode). USE THIS instead of sap_transaction('SM30') - faster and returns structured data. Returns entries from the maintenance view with dynamically-parsed columns. Supports any flat table view (e.g., V_T005 for countries, custom Z* views). Non-flat views (SM34/cluster/hierarchical) are detected and reported as unsupported. Note: only the first page of rows is returned (typically ~12 rows); views with more entries will report the total row_count from the view header.

Inputs: view_name (required), session, agent_id, output_file. Returns: result

sap_sm37_lookupSap Sm37 LookupA
Read-only

List background jobs from SM37 (Job Overview). USE THIS instead of sap_transaction('SM37') - faster and returns structured data.

Filters: job name (wildcards like BILLING), username, status (scheduled/released/ready/active/finished/canceled), date range.

Note: status=None keeps SAP defaults (all checked except 'Scheduled'). Pass status=['scheduled'] explicitly to include only scheduled jobs.

When include_log=True and exactly one job matches, the job log is included.

Returns job list with name, status, start time, duration, user, and SAP client (mandant).

Inputs: status, session, to_date, agent_id, +5 more. Returns: Result of SM37 job list lookup.

sap_st22_lookupSap St22 LookupA
Read-only

Look up ABAP short dumps (runtime errors) from ST22. If sap-adt is available, prefer its list_short_dumps/get_short_dump_details tools. USE THIS instead of sap_transaction('ST22') - faster and returns structured data. Two-step workflow: call once without dump_index to list dumps, then call again with dump_index=N to read a specific dump's detail. By default lists today's dumps. Use date parameter for other dates.

Inputs: date, session, agent_id, dump_index, +1 more. Returns: result

sap_transactionSap TransactionA

Enter and execute an SAP transaction code. IMPORTANT: Do NOT use this for SE11, SE16, SE24, SE37, or SE93; use sap_se11_lookup, sap_se16_query, sap_se24_lookup, sap_se37_lookup, or sap_se93_lookup.

Multi-Session Support (for parallel agents): new_window=True opens a new SAP session and returns session_id/session_count; pass session on later calls to target it.

Concurrency note: SAP GUI COM scripting is single-threaded per connection. Running parallel scripting loops across new_window=True sessions of the same connection is serialized (no speedup). For bulk work on one connection, use one script with a larger loop; parallelize only across separate connections.

⚠️ CRITICAL: Always close sessions you opened! Close new_window=True sessions with sap_session_close to avoid hitting SAP session limits. Use sap_session_list to review open IDs.

Inputs: tcode (required), session, agent_id, new_window, +1 more. Returns: Result from sap_transaction tool.

search_classesSearch ClassesA
Read-only

Search for SAP classes by name or description. Use this when the user asks things like:

  • 'What class handles installations?'

  • 'Find classes for IS-U contracts'

  • 'Which class works with devices?'

  • 'Show me FI-CA classes'

The catalog contains IS-U and FI-CA classes. Returns matching classes with relevance scores.

Inputs: query (required), limit. Returns: Response from class search.

search_function_modulesSearch Function ModulesA
Read-only

Search for SAP function modules by name, description, or parameter. Use this when the user asks things like:

  • 'What FM reads installation data?'

  • 'Find function modules for Anlage'

  • 'Which FMs work with business partners?'

  • 'Show me FKK function modules'

The catalog contains IS-U and FI-CA function modules. Returns matching FMs with relevance scores.

Inputs: query (required), limit, include_params. Returns: Response from function module search.

search_tablesSearch TablesA
Read-only

Search for SAP tables by name, description, or field. Use this when the user asks things like:

  • 'What table stores material master data?'

  • 'Which table has the MATNR field?'

  • 'Find tables related to purchase orders'

Returns matching tables with relevance scores.

Inputs: query (required), limit, include_fields. Returns: Response from table search.

search_transactionsSearch TransactionsA
Read-only

Search for SAP transactions by description or transaction code. Use this when the user asks things like:

  • 'How do I create a sales order?'

  • 'What transaction displays customer master?'

  • 'Show me material management transactions'

  • 'What is VA01?'

Returns matching transactions with relevance scores.

Inputs: query (required), area, limit. Returns: Response from transaction search. NOTE: `success` is always True because this t…

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 71 tools

    Disambiguation2/5

    Many tools are transaction- or object-specific, but the set contains clear overlaps: sap_get_form_fields vs sap_discover_fields, sap_set_field vs sap_select_dropdown/sap_fill_form, sap_screenshot vs browser_screenshot, and browser_* UI controls vs the SAP-native click/fill/keyboard tools. Descriptions give preferred-order hints, but boundaries remain fuzzy enough that an agent can easily choose the wrong discovery or interaction tool.

    Naming Consistency3/5

    All names use lower_snake_case, but there is no uniform verb_noun pattern: sap_get_screen_text and sap_set_field coexist with sap_transaction, sap_session_list, sap_keepalive_start, and sap_abapgit_list_repos. The sap_*, browser_*, search_*, log_*, and bare choose prefixes namespace some tools, but verb order and prefix conventions are mixed.

    Tool Count1/5

    At 71 tools this surface is extremely oversized for a single MCP server, even for the broad SAP GUI automation domain. It includes overlapping UI layers, auxiliary logging/choice tools, and multiple session-management utilities that would be better consolidated or split into focused servers.

    Completeness4/5

    Coverage is unusually broad: login/session management, screen/form interaction, transactions, table/query lookups, ABAP metadata and editing, transports, logs, jobs, dumps, IMG search, and abapGit. Gaps remain around ABAP debugger control and creating new ABAP objects, but those are explicitly scoped limitations rather than fatal omissions.

    Maintenance

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      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.
      12
      147
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI platforms to see the screen and operate any desktop software through real mouse clicks, text input, key presses, and scripted scenario execution.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to execute SAP tasks through a cost-routing MCP server that tries API, recorded scripts, WebGUI, and computer-use vision in cheapest-first order, falling back only when needed. It can also promote an interactive GUI routine into a reusable recorded script to make repeat runs nearly free.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI tools to operate IBM i 5250 green screens, driving and testing interactive RPG programs by seeing screens, typing into fields, and pressing keys.
      6
      20 npm
      1
      Apache 2.0

    Appeared in Searches