SAP GUI MCP Server

An MCP (Model Context Protocol) server for SAP automation. Control SAP through Claude Desktop, Claude Code, or opencode - via SAP GUI desktop or SAP Web GUI (browser). 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 - tasks a pure REST-API client cannot do. The MCP works with both SAP R/3 and S/4.

[!TIP] Try it yourself: this demo is a skill that ships with this repository - clone it (or copy .claude/skills/readme-demo/ into your project), then ask your agent to run the readme demo (or invoke /readme-demo in Claude Code) - it logs into your system, creates a business partner, screenshots it, and verifies it in SE16. It needs the desktop backend (SAP GUI for Windows with scripting enabled), because the screenshots are saved via sap_run_script.

[!NOTE] Pairs with aibap.mcp. The two servers complement each other in a two-agent vibe-coding setup: one agent writes ABAP via aibap.mcp (ADT REST), while a second agent drives this server to test the generated code in the real SAP UI, capture screenshots, and report failures back. See AIBAP_TEMPLATE_REPOSITORY for a template that documents this workflow end-to-end.

[!TIP] Save tokens with sap_run_script! 🚀 Instead of dozens of back-and-forth tool calls, the AI agent can write and execute a single Python script that loops, branches, and collects results - all in one shot. You just describe what you need; the agent generates the script automatically. Perfect for repetitive workflows like reading 50 table rows or bulk-updating fields. Runs in a secure sandbox against the SAP GUI COM API. Desktop backend only. See Capabilities.

Developer? See ARCHITECTURE.md for codebase structure, request flow diagrams, and how to add new transaction tools. The Development Setup section at the bottom of this page covers running from source.

Setup

Pick an installation method below - each one walks you through two things: creating your SAP credentials file (systems.json) and registering the MCP server with your AI client.

[!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 tool. Here, credentials 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.

Choose one of these three approaches:

Where to register the MCP server:

• Claude Code - register once for all projects with claude mcp add --scope user (recommended), or per project in .mcp.json in the project root. Each section below shows both.
• Claude Desktop - add to claude_desktop_config.json (global config, path varies by OS - shown in each section below)
• opencode - add to opencode.json in your project root. Each section below includes a ready-to-use opencode.json snippet alongside the Claude Code snippet.

[!WARNING] Special characters in passwords: 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.

Download the binary for your platform from GitHub Releases:

Platform	Binary
Windows (x64)	sapgui_mcp_windows_<version>.exe
macOS (Apple Silicon)	sapgui_mcp_macos_arm64_<version>

Smart App and other Security Tools

Tip

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.

Note

The macOS binary supports the WebGUI backend only (browser automation). The desktop backend requires SAP GUI for Windows (COM Scripting) and is not available on macOS.

macOS Gatekeeper: If macOS refuses to run the binary, clear the quarantine attribute: xattr -c sapgui_mcp_macos_arm64_<version>

Choose a backend:

	Desktop Backend (SAP GUI)	WebGUI Backend (Browser)
Platform	Windows only	Windows, macOS, Linux
Requires	SAP GUI for Windows	Chrome browser
Speed	Faster (works directly with SAP GUI)	Slower (works through a web browser)
Setup	Simpler (just SAP GUI + this tool)	More steps (also needs Chrome browser setup)

Option A: Desktop Backend (SAP GUI) - recommended for Windows users

Automates SAP GUI directly - no browser needed. Windows only. Uses sapsucker for typed SAP GUI Scripting access.

Prerequisites:

• SAP GUI for Windows installed (standard path - the server finds it automatically via Windows registry)
• SAP GUI Scripting enabled (one-time setup, see below)

Server side (requires admin/basis team):

• Transaction RZ11 → parameter sapgui/user_scripting → set to TRUE
• Dynamic parameter - no server restart needed, but users must re-login (close and reopen SAP GUI)

Client side (your PC):

1. Open SAP Logon or any SAP GUI session
2. Go to Options (via menu bar, tray icon, or press Alt+F12 in a session)
3. Navigate to Accessibility & Scripting → Scripting (DE: Barrierefreiheit & Skripting → Skripting)
4. Check "Enable Scripting" (DE: "Skripting aktivieren")
5. Uncheck "Notify when a script attaches to SAP GUI"
6. Uncheck "Notify when a script opens a connection"

[!IMPORTANT] The two notification checkboxes must be unchecked. If left checked, every COM connection triggers a modal popup that blocks automation.

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

This file holds your SAP credentials and is shared with aibap.mcp - configure it once and all Hochfrequenz SAP MCP servers will use it.

On Windows, open Windows Explorer and paste this into the address bar:

%USERPROFILE%\.config\sap-mcp

Create the folder if it doesn't exist, then create a file called systems.json inside it. On macOS/Linux, the path is ~/.config/sap-mcp/systems.json.

There are two distinct identifiers per system - don't mix them up:

Concept	Example	Where it's used
System key (dictionary key)	"dev", "qa"	sap_login(system_key="qa") - selects which system to log into
SAP Logon entry (connection_name field)	"DEV S/4HANA", "DEV - ERP Development"	Must match the bold description in the SAP Logon pad exactly

The SAP Logon entry is not the 3-character System ID (SID):

What you see in SAP Logon	connection_name value	NOT this (SID)
DEV S/4HANA	"DEV S/4HANA"	"XYZ"
DEV - ERP Development	"DEV - ERP Development"	"DEV"

If the connection_name doesn't match exactly, you'll get "SAP Logon connection entry not found".

{
    "default_system": "dev",
    "systems": {
        "dev": {
            "connection_name": "DEV S/4HANA",
            "host": "https://your-sap-system:44300",
            "client": "100",
            "user": "your_username",
            "password": "your_password",
            "language": "DE"
        }
    }
}

[!NOTE] If your SAP system uses a self-signed or internally-signed certificate (common for VPN/intranet systems), add "tls_skip_verify": true to the system entry. Leave it out if your system has a publicly-trusted certificate.

[!IMPORTANT] After editing systems.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 - connection_name, 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, their hosts and connection names - 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.

See sap-mcp-config for the complete field reference - all optional fields, validation rules, YAML support, ${env:VAR} placeholder rules, and a visual guide to finding your connection_name in SAP Logon.

Step 2: Configure your MCP client

[!TIP] Note the full path to the downloaded .exe. For example, if you saved sapgui_mcp_windows_1.5.0.exe to your Downloads folder, the path is C:/Users/YourName/Downloads/sapgui_mcp_windows_1.5.0.exe. Always use forward slashes (/) in JSON, not backslashes (\).

Claude Desktop

Add to claude_desktop_config.json. To open the file: press Win+R, type %APPDATA%\Claude, press Enter. 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).

{
    "mcpServers": {
        "sap-desktop": {
            "command": "C:/path/to/sapgui_mcp_windows_<version>.exe",
            "env": {
                "BACKEND_TYPE": "desktop"
            }
        }
    }
}

Claude Code

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

claude mcp add --scope user sap-desktop -e BACKEND_TYPE=desktop '--' C:/path/to/sapgui_mcp_windows_<version>.exe

Together with systems.json, this is all Claude Code needs - no .mcp.json in any project folder. Two details matter:

• Keep the server name (sap-desktop) 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 .exe 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.

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-desktop": {
            "command": "C:/path/to/sapgui_mcp_windows_<version>.exe",
            "env": {
                "BACKEND_TYPE": "desktop"
            }
        }
    }
}

opencode

Add to opencode.json in your project root:

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

[!TIP] In opencode.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.

Multi-system access (desktop backend only)

Multi-system support is built into systems.json - add multiple systems and the LLM can switch between them:

How it works:

1. sap_list_connections returns both configured systems (from systems.json) and SAP Logon entries (from SAPUILandscape.xml).
2. sap_login(system_key="qa") logs into a specific system using credentials from systems.json.

Configuration: Add multiple systems to your systems.json. The dictionary key (e.g. "dev", "qa") is the system_key you pass to sap_login. The connection_name field must match the SAP Logon entry description exactly:

{
    "default_system": "dev",
    "systems": {
        "dev": {
            "connection_name": "DEV S/4HANA",
            "host": "https://dev-sap:44300",
            "client": "100",
            "user": "dev_user",
            "password": "dev_pass",
            "language": "DE"
        },
        "qa": {
            "connection_name": "QA System",
            "host": "https://qa-sap:44300",
            "client": "200",
            "user": "qa_user",
            "password": "qa_pass",
            "language": "EN"
        }
    }
}

When sap_login(system_key="qa") is called, it looks up "qa" in systems.json, reads the credentials, and uses the connection_name field ("QA System") to open the matching SAP Logon entry. If the system key is not found, an error is returned listing the available keys.

No Chrome, no browser setup required.

Verify the setup

Before your first prompt, check that the MCP server starts correctly. Open PowerShell and run:

Claude Code:

claude mcp list

Expected output:

sap-desktop: C:/path/to/sapgui_mcp_windows_<version>.exe ✓ Connected

opencode:

opencode mcp list

Expected output:

● ✓ sap-desktop connected

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

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

[!TIP] Getting started: Restart Claude Desktop, Claude Code, or opencode, then try: "Log me into SAP" or "Run transaction SE16". SAP GUI will open automatically if it is not already running.

Option B: WebGUI Backend (Browser)

Automates SAP Web GUI through Chrome browser automation. Works on all platforms. This is the default - if you don't set BACKEND_TYPE, the server uses WebGUI.

Step 1: Start Chrome with remote debugging

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

[!NOTE] Chrome path may differ. The path above is for a system-wide Chrome installation. If Chrome was installed only for your user, the path is typically:

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

Not sure where Chrome is installed? See Finding your Chrome path in the Troubleshooting section below.

Step 2: Create systems.json

Create the SAP config file if you haven't already (Windows: %USERPROFILE%\.config\sap-mcp\systems.json, macOS/Linux: ~/.config/sap-mcp/systems.json). See sap-mcp-config for the full field reference and YAML support.

{
    "default_system": "dev",
    "systems": {
        "dev": {
            "host": "https://your-sap-server:44300",
            "client": "100",
            "user": "your_username",
            "password": "your_password",
            "language": "DE"
        }
    }
}

[!NOTE] If your SAP system uses a self-signed or internally-signed certificate (common for VPN/intranet systems), add "tls_skip_verify": true to the system entry. Leave it out if your system has a publicly-trusted certificate.

[!NOTE] The WebGUI backend connects directly to the host URL - there is no SAP Logon application involved, so connection_name is not needed here (unlike the Desktop backend).

[!NOTE] The WebGUI URL is derived automatically from host as {host}/sap/bc/gui/sap/its/webgui. If your SAP system uses a non-standard WebGUI path, set SAP_URL in the MCP config below.

Step 3: Configure your MCP client

Claude Desktop

Add to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

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/sapgui_mcp_windows_<version>.exe

Together with systems.json, no .mcp.json is needed in any project folder. On macOS, use the path to sapgui_mcp_macos_arm64_<version> instead; the command works unchanged in bash and zsh. Keep the quotes around '--' in PowerShell (in cmd.exe, write a plain --), and if you add environment variables with -e, put them between the server name (sap-webgui) and '--' - see the Desktop backend section for why both matter.

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/sapgui_mcp_windows_<version>.exe",
            "env": {}
        }
    }
}

opencode

Add to opencode.json in your project root:

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

[!TIP] In opencode.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.

[!NOTE] GITHUB_PAT is optional - only needed for log_feedback (creates GitHub issues) and abapGit operations with private repos. Add it to the env / environment block only if you need those features.

No Docker, no CDP proxy, no Python required.

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/sapgui_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 .exe. Run opencode mcp debug sap-webgui for more detail.

For Claude Code, with a user-scope registration, claude mcp get sap-webgui shows the registered path; to change it, run claude mcp remove sap-webgui -s user and add the server again.

[!TIP] Getting started: Restart Claude Desktop, Claude Code, or opencode, then try: "Log me into SAP" or "Take a screenshot of the current SAP screen".

This guide gets you running with Docker on Windows - no Python or cloning required.

The setup is similar on macOS, with these differences:

Chrome command:

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

Verify Chrome:

curl http://localhost:9222/json/version

Config file location:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Everything else (Docker setup, CDP proxy, MCP config) is identical.

Prerequisites

• Docker Desktop for Windows (download)
• Chrome browser
• VPN client connected (if your SAP system is on an internal network)

Verify Docker is running:

docker --version

Step 1: Start Chrome with remote debugging

Chrome must be started with special flags to allow automation. Run in PowerShell:

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

[!NOTE] Chrome path may differ. If Chrome was installed only for your user, replace the path:

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

See Finding your Chrome path below if the command fails.

Verify it's working:

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

You should see a JSON response. If you get a connection error, make sure you included the --user-data-dir flag.

Step 2: Set up the CDP proxy

Docker containers can't connect directly to Chrome on your host. The CDP proxy solves this.

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

Step 3: Configure your MCP client

Required: systems.json with your SAP credentials (see sap-mcp-config and Configuration Reference for the default path per OS). All other env variables are optional. See Configuration Reference for the full list.

[!NOTE] GITHUB_PAT is only needed for log_feedback (creates GitHub issues) or abapGit operations. Remove -e GITHUB_PAT=... if you don't need these features.

Choose one of the following options based on which Claude client you use.

Option A: Claude Desktop

Open %APPDATA%\Claude\claude_desktop_config.json and add:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--network",
                "sap-mcp-network",
                "-e",
                "BROWSER_MODE=connect",
                "-e",
                "CDP_URL=http://cdp-proxy:9222",
                "-e",
                "SAP_URL=https://your-sap-server/sap/bc/gui/sap/its/webgui",
                "-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/sapgui.mcp:latest"
            ]
        }
    }
}

Replace:

• your-sap-server with your SAP server hostname
• your_github_pat with a GitHub Personal Access Token (optional - see note above)
• C:/Users/YourName with your home folder (on macOS, use /Users/YourName/... instead of C:/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.
• SAP credentials (user, password, client, language) are read from systems.json, which is volume-mounted into the container

Option B: Claude Code

Recommended: register once for all projects (user scope):

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 -e SAP_URL=https://your-sap-server/sap/bc/gui/sap/its/webgui -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/sapgui.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 the Desktop backend section for why). Replace C:/Users/YourName with your home folder; write the path out in full instead of using ~, because how ~ is expanded on the command line depends on the shell. Note that a GITHUB_PAT typed on the command line ends up in your shell history.

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": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "--network",
                "sap-mcp-network",
                "-e",
                "BROWSER_MODE=connect",
                "-e",
                "CDP_URL=http://cdp-proxy:9222",
                "-e",
                "SAP_URL=https://your-sap-server/sap/bc/gui/sap/its/webgui",
                "-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/sapgui.mcp:latest"
            ]
        }
    }
}

Step 4: Start chatting

Restart Claude Desktop/Code and try:

• "Log me into SAP"
• "Run transaction VA01"
• "Take a screenshot"

If it tries e.g. to start a dev-browser or install Chrome, cancel and try to be explicit "log me into sap using the sap web gui mcp". If Docker Desktop isn't running or you're not logged in (docker login ghcr.io) and never pulled the image, you might get a nonspecific error "1 MCP server failed · /mcp".

[!WARNING] You need to be logged in to the GitHub Container Registry (ghcr.io). Being logged in to Docker (for example Docker Hub) alone is not sufficient; you must run docker login ghcr.io.

Try pulling manually if you run into errors:

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

If the containers started but Chrome (in browser automation mode with CDP enabled) is missing, Claude will likely understand how to login but fail on the first tool call.

For contributors who want to run from source.

Prerequisites

• Python 3.11+
• Chrome browser with remote debugging (see Step 1 above)

Clone and install

git clone https://github.com/Hochfrequenz/sapgui.mcp.git
cd sapgui.mcp
# Install uv: https://docs.astral.sh/uv/getting-started/installation/
uv sync --group dev
uv run playwright install chromium

Run tests

uv run --group tests python -m pytest unittests/ -k "not integration and not exploration"  # unit tests only
uv run --group linting ruff check .                                                         # code quality
uv run --group linting ruff format --check .                                                # check formatting

Run the MCP server locally

# Set environment variables
$env:SAP_URL = "https://your-sap-server/sap/bc/gui/sap/its/webgui"
$env:BROWSER_MODE = "connect"
$env:CDP_URL = "http://localhost:9222"

# Start the server
run-sapgui-mcp-server

Configure your MCP client

Required: systems.json with your SAP credentials (see sap-mcp-config and Configuration Reference for the default path per OS). All other env variables are optional.

[!NOTE] GITHUB_PAT is only needed for log_feedback (creates GitHub issues) or abapGit operations. Remove it if you don't need these features.

When running Python directly (not in Docker), you don't need the CDP proxy - Python can connect to Chrome on localhost.

Claude Desktop

Add to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
    "mcpServers": {
        "sap-webgui": {
            "command": "C:/path/to/your/venv/Scripts/run-sapgui-mcp-server.exe",
            "args": [],
            "env": {
                "BROWSER_MODE": "connect",
                "CDP_URL": "http://localhost:9222",
                "GITHUB_PAT": "your_github_pat"
            }
        }
    }
}

Claude Code

Recommended: register once for all projects (user scope):

claude mcp add --scope user sap-webgui -e BROWSER_MODE=connect -e CDP_URL=http://localhost:9222 -e GITHUB_PAT=your_github_pat '--' C:/path/to/your/venv/Scripts/run-sapgui-mcp-server.exe

Keep the server name before -e and the quotes around '--' (in cmd.exe, write a plain --; see the Desktop backend section for why). A GITHUB_PAT typed on the command line ends up in your shell history.

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/your/venv/Scripts/run-sapgui-mcp-server.exe",
            "args": [],
            "env": {
                "BROWSER_MODE": "connect",
                "CDP_URL": "http://localhost:9222",
                "GITHUB_PAT": "your_github_pat"
            }
        }
    }
}

Capabilities

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

• Drive Any SAP Transaction — Execute transaction codes, fill form fields, click buttons, navigate tabs, read and interact with ALV grids and tables, and handle modal popups and status bar messages.
• Transaction Shortcuts — Built-in workflows for common developer and basis tasks: query tables (SE16/SE16N), inspect transports (SE09/SE10), search background jobs (SM37), inspect short dumps (ST22), query application logs (SLG1), maintain table views (SM30), and look up Data Dictionary objects (SE11).
• High-Performance Scripting (sap_run_script) — For bulk operations or complex multi-step workflows, the agent can write and run sandboxed Python scripts against the SAP GUI COM API in a single round-trip instead of dozens of tool calls. (Desktop backend only; sandbox contract exposed via sandbox://sap_run_script).
• Visual Validation & Screenshots — Capture screenshots of any SAP screen for documentation, E2E test verification, or human-in-the-loop inspection.
• Offline Catalogs — Search transaction codes, tables, classes, and function modules instantly without an active SAP connection.
• abapGit & Source Code — Pull abapGit repositories and inspect ABAP report source code. Pulls use the Z_ABAPGIT_PULL_MCP_SHORTCUT report on the SAP system. For private repositories, set GITHUB_PAT or ABAPGIT_PAT.
• Multi-Session Management — List, bind, release, and switch between parallel SAP GUI sessions across concurrent agent tasks.
• Browser Automation (WebGUI) — When using the WebGUI backend, low-level browser actions (click, fill, keyboard, screenshot, DOM snapshot) are available as escape hatches for pixel-level control.

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. Older versions read SAP_USER, SAP_PASSWORD, SAP_MANDANT, SAP_LANGUAGE, SAP_CONNECTION_NAME and SAP_CREDENTIALS from the MCP config's env block; these are ignored now and can be removed from existing configs.

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 connection_name, 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. A few tools that only list configuration, such as sap_list_connections, tolerate an invalid config and simply return nothing. 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)

Variable	Required	Description	Default
BACKEND_TYPE	No	webgui (browser automation) or desktop (SAP GUI COM, Windows only)	webgui
SAP_URL	No	Override WebGUI URL (default: derived from host in systems.json)	""
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)
SCRIPT_ROOTS	No	Allowed root directories for sap_run_script's script_path parameter, separated by os.pathsep (; on Windows, : on macOS/Linux). Roots must be absolute paths (relative entries are skipped with a warning); a UNC/network root is allowed if you configure one, whereas UNC/device paths in the caller's script_path are rejected. Relative script_path values are resolved against these roots in order (first match wins). Desktop backend only.	"" (script_path disabled)
BROWSER_MODE	No	connect (existing Chrome) or launch (Playwright). WebGUI only.	connect
BROWSER_TYPE	No	chromium, firefox, or webkit. WebGUI only.	chromium
BROWSER_HEADLESS	No	Run browser in headless mode. WebGUI only.	false
CDP_URL	When BROWSER_MODE=connect	Chrome DevTools Protocol URL. WebGUI only.	http://localhost:9222
CHROME_PATH	No

Logging

The server logs to stdout by default using a structured text format. Set LOG_FORMAT=json for machine-readable JSON output.

Papertrail (remote logging)

Remote logging to Papertrail is disabled by default. No telemetry is sent unless you explicitly opt in.

To enable it, set both PAPERTRAIL_HOST and PAPERTRAIL_PORT in your .env file or environment:

PAPERTRAIL_HOST=logs.example.com
PAPERTRAIL_PORT=12345

When enabled, tool call names, SAP hostnames, and operational metadata are sent to the configured Papertrail endpoint for monitoring and debugging. No SAP credentials or business data are transmitted.

Each release publishes binaries for Windows and macOS:

Binary	Papertrail default	Intended audience
sapgui_mcp_windows.exe	off - no defaults bundled	Public / external users
sapgui_mcp_windows_with_remote_logging.exe	Hochfrequenz endpoint baked in at build time	Hochfrequenz-internal use
sapgui_mcp_macos_arm64	off - no defaults bundled	Public / macOS (Apple Silicon) users

Both binaries 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

"network sap-mcp-network not found"

The CDP proxy isn't running or was never started. Start it:

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

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 existing instance)
3. Verify with: Invoke-WebRequest -Uri 'http://localhost:9222/json/version' -UseBasicParsing

"Cannot connect to CDP proxy"

Check if the proxy is running:

docker ps | Select-String cdp-proxy

Check proxy logs:

docker logs sap-mcp-cdp-proxy-1

SAP login fails

• Check SAP_URL is correct and accessible from your browser
• If using auto-login, verify credentials are configured in systems.json (see Configuration Reference)
• Desktop backend: Make sure the connection_name field in systems.json matches the SAP Logon pad description exactly (the bold text, not the SID). Open SAP Logon and compare.
• 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 (shown for sap-desktop; use sap-webgui for the WebGUI backend):

• Run claude mcp get sap-desktop from the project directory. The Scope: line shows which registration Claude Code actually uses.
• Remove a local-scope entry with claude mcp remove sap-desktop -s local, or the entry in the project's .mcp.json with claude mcp remove sap-desktop -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 versions, you can also drop the old SAP_* credential variables from any env block - see SAP Credentials for the list. 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)

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. Check Docker container logs: docker logs <container-id>

"Port 9223 already in use"

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

If you see "unauthorized" or "access denied" when pulling the image, you need to authenticate with GitHub Container Registry.

Step 1: Create a GitHub Personal Access Token

1. Go to GitHub Token Settings
2. Click "Generate new token" → "Generate new token (classic)"

   You must use "classic" tokens. Fine-grained tokens don't support container registry access.

3. Give it a name like "Docker GHCR read"
4. Set expiration: Choose "Custom" and set to 1 year. You'll need to create a new token and re-login when it expires
5. Select scope: read:packages (only this one is needed)
6. Click "Generate token"
7. Copy the token immediately (starts with ghp_) - you won't see it again!

Step 2: Login to GitHub Container Registry

docker login ghcr.io -u YOUR_GITHUB_USERNAME

When prompted for password:

• Paste your Personal Access Token (not your GitHub password)
• The password won't show as you type - this is normal
• In PowerShell, right-click to paste (Ctrl+V may not work)

You should see: Login Succeeded

Step 3: Pull the image

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

[!NOTE] You only need to do this once per machine. Docker stores your credentials.

Still having issues?

• Verify the token starts with ghp_
• Try: docker logout ghcr.io then repeat Step 2

Architecture

The server supports two backends. Choose one via BACKEND_TYPE.

WebGUI Backend (BACKEND_TYPE=webgui, default):

graph BT
    Claude["Claude Desktop / Claude Code"]
    MCP["MCP Server (sapguimcp)\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

Desktop Backend (BACKEND_TYPE=desktop, Windows only):

graph BT
    Claude["Claude Desktop / Claude Code"]
    MCP["MCP Server (sapguimcp)\nDesktop backend with COM thread\nSAP-specific tools"]
    SAP["SAP GUI for Windows\nCOM Scripting API\nPersistent session(s)"]

    Claude -- "MCP (stdio)" --> MCP
    MCP -- "COM (pywin32)" --> SAP

Related projects

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

• 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 sapgui.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 sapgui.mcp) 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 both sapgui.mcp (Python) and aibap.mcp (Go).

Contributing

See CONTRIBUTING.md for development setup, testing, and coding standards.