Sapgui Mcp

SAP GUI MCP Server

[](https://github.com/Hochfrequenz/sapgui.mcp/actions) [](https://github.com/Hochfrequenz/sapgui.mcp/actions) [](https://github.com/Hochfrequenz/sapgui.mcp/actions) [](https://github.com/Hochfrequenz/sapgui.mcp/actions)

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.

> [!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 [Desktop COM Tools](#desktop-com-tools-desktop-backend-only).

> Developer? See [ARCHITECTURE.md](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 - add to .mcp.json in your project root (per-project config)
• 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.

📦 Standalone Executable (recommended - no Docker, no Python)

Download the binary for your platform from GitHub Releases:

| Platform | Binary | | ---------------- | ----------------------------------------- | | Windows (x64) | sapgui_mcp_windows_.exe | | macOS (Apple Silicon) | sapgui_mcp_macos_arm64_ |

> [!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_

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)

Enable SAP GUI Scripting (one-time)

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) | "HF S/4", "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) | | ------------------------- | --------------------------- | -------------- | | HF S/4 | "HF S/4" | ~~"HFQ"~~ | | 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": "HF S/4",
            "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.

See sap-mcp-config for the complete field reference - all optional fields, validation rules, YAML support, 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_.exe",
            "env": {
                "BACKEND_TYPE": "desktop"
            }
        }
    }
}

Claude Code

Add to .mcp.json in your project root:

{
    "mcpServers": {
        "sap-desktop": {
            "command": "C:/path/to/sapgui_mcp_windows_.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_.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": "HF S/4",
            "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_.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.

> [!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: > > ``powershell > & "$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](#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_.exe",
            "env": {}
        }
    }
}

Claude Code

Add to .mcp.json in your project root:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "C:/path/to/sapgui_mcp_windows_.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_.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 i

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Hochfrequenz
• Source: Hochfrequenz/sapgui.mcp
• License: MIT

Install and usage instructions live in the source repository linked above.