MCP server for SAP GUI automation (KTern.AI fork)

These details have not been verified by PyPI

Project links

Project description

KTern SAP GUI MCP Server

An MCP (Model Context Protocol) server for SAP GUI automation, maintained by KTern.AI. Control SAP through any MCP-compatible AI client — via SAP GUI desktop (COM Scripting) or SAP Web GUI (browser automation).

Based on sapgui.mcp by Hochfrequenz Unternehmensberatung GmbH (MIT License).

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. Works with both SAP R/3 and S/4HANA.

Quick Start (uvx)

No installation needed — just run directly with uvx:

uvx ktern-sapguimcp

Prerequisites

uv installed (installation guide)
SAP credentials configured in ~/.config/sap-mcp/systems.json
For Desktop mode: SAP GUI for Windows with scripting enabled (Windows only)
For WebGUI mode: Chrome browser

Setup

Step 1: Create `systems.json`

This file holds your SAP connection credentials.

Path: ~/.config/sap-mcp/systems.json (Linux/macOS) or %USERPROFILE%\.config\sap-mcp\systems.json (Windows)

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

Notes:

For Desktop mode, connection_name must match the SAP Logon pad entry exactly (the bold description text, not the SID)
For WebGUI mode, host is used to derive the WebGUI URL automatically ({host}/sap/bc/gui/sap/its/webgui)
Add "tls_skip_verify": true if your SAP system uses a self-signed certificate

Don't want to use ~/.config/sap-mcp/? You can put systems.json anywhere and point to it with SAP_CONFIG_FILE:

"environment": {
    "BACKEND_TYPE": "desktop",
    "SAP_CONFIG_FILE": "./systems.json"
}

Or skip the file entirely — pass credentials directly as environment variables:

"environment": {
    "BACKEND_TYPE": "desktop",
    "SAP_HOST": "https://your-sap-server:44300",
    "SAP_USER": "your_username",
    "SAP_PASSWORD": "your_password",
    "SAP_CLIENT": "100",
    "SAP_CONNECTION_NAME": "SAP DEV",
    "SAP_LANGUAGE": "EN"
}

When SAP_HOST + SAP_USER + SAP_PASSWORD are set, the server uses them directly — no file needed. This is the simplest setup for single-system configurations.

Env Variable	Required	Description
`SAP_HOST`	Yes	SAP server URL (e.g. `https://sap:44300`)
`SAP_USER`	Yes	SAP username
`SAP_PASSWORD`	Yes	SAP password
`SAP_CLIENT`	No	Client/mandant (e.g. `100`)
`SAP_CONNECTION_NAME`	No	SAP Logon entry name (desktop mode only)
`SAP_LANGUAGE`	No	Login language (default: `EN`)
`SAP_TLS_SKIP_VERIFY`	No	Skip TLS verification (`true`/`false`)

Priority: Env vars > SAP_CONFIG_FILE > ~/.config/sap-mcp/systems.json

Step 2: Configure Your MCP Client

Platform note: Desktop mode requires native Windows (COM Scripting). It does NOT work in WSL, macOS, or Linux. If you're in WSL, use WebGUI mode or run the server from the Windows side.

Desktop Mode (SAP GUI COM — Windows only)

Automates SAP GUI directly via COM Scripting. Faster, no browser needed. Must run on native Windows (not WSL).

uvx (recommended)

Kiro / Claude Code — .kiro/settings/mcp.json or .mcp.json:

{
    "mcpServers": {
        "sap-desktop": {
            "command": "uvx",
            "args": ["ktern-sapguimcp"],
            "env": {
                "BACKEND_TYPE": "desktop",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_CONNECTION_NAME": "SAP DEV",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

opencode — opencode.json:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sap-desktop": {
            "type": "local",
            "command": ["uvx", "ktern-sapguimcp"],
            "enabled": true,
            "environment": {
                "BACKEND_TYPE": "desktop",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_CONNECTION_NAME": "SAP DEV",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

Claude Desktop — claude_desktop_config.json:

{
    "mcpServers": {
        "sap-desktop": {
            "command": "uvx",
            "args": ["ktern-sapguimcp"],
            "env": {
                "BACKEND_TYPE": "desktop",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_CONNECTION_NAME": "SAP DEV",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

Local run (from source / venv)

Kiro / Claude Code — .kiro/settings/mcp.json or .mcp.json:

{
    "mcpServers": {
        "sap-desktop": {
            "command": "C:/path/to/sapgui.mcp/.venv/Scripts/python.exe",
            "args": ["-m", "sapguimcp.server"],
            "env": {
                "BACKEND_TYPE": "desktop",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_CONNECTION_NAME": "SAP DEV",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

opencode — opencode.json:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sap-desktop": {
            "type": "local",
            "command": ["C:/path/to/sapgui.mcp/.venv/Scripts/python.exe", "-m", "sapguimcp.server"],
            "enabled": true,
            "environment": {
                "BACKEND_TYPE": "desktop",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_CONNECTION_NAME": "SAP DEV",
                "SAP_LANGUAGE": "EN"
            },
            "timeout": 120000
        }
    }
}

Important: Use the Windows Python path (C:/path/to/.venv/Scripts/python.exe), not a WSL path. Desktop mode requires native Windows execution.

Prerequisites for Desktop mode:

Windows (native, not WSL)
SAP GUI for Windows installed
SAP GUI Scripting enabled:
- Server side: RZ11 → sapgui/user_scripting → TRUE
- Client side: SAP GUI Options → Accessibility & Scripting → Enable Scripting
- Uncheck both notification checkboxes (they block automation)

WebGUI Mode (Browser — all platforms)

Automates SAP Web GUI through Chrome. Works on Windows, macOS, Linux, and WSL.

uvx (recommended)

Kiro / Claude Code — .kiro/settings/mcp.json or .mcp.json:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "uvx",
            "args": ["ktern-sapguimcp"],
            "env": {
                "BACKEND_TYPE": "webgui",
                "BROWSER_MODE": "launch",
                "BROWSER_HEADLESS": "true",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

opencode — opencode.json:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sap-webgui": {
            "type": "local",
            "command": ["uvx", "ktern-sapguimcp"],
            "enabled": true,
            "environment": {
                "BACKEND_TYPE": "webgui",
                "BROWSER_MODE": "launch",
                "BROWSER_HEADLESS": "true",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

Claude Desktop — claude_desktop_config.json:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "uvx",
            "args": ["ktern-sapguimcp"],
            "env": {
                "BACKEND_TYPE": "webgui",
                "BROWSER_MODE": "launch",
                "BROWSER_HEADLESS": "true",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

Local run (from source / venv)

Kiro / Claude Code — .kiro/settings/mcp.json or .mcp.json:

{
    "mcpServers": {
        "sap-webgui": {
            "command": "/path/to/sapgui.mcp/.venv/bin/python",
            "args": ["-m", "sapguimcp.server"],
            "env": {
                "BACKEND_TYPE": "webgui",
                "BROWSER_MODE": "launch",
                "BROWSER_HEADLESS": "true",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_LANGUAGE": "EN"
            }
        }
    }
}

opencode — opencode.json:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "sap-webgui": {
            "type": "local",
            "command": ["/path/to/sapgui.mcp/.venv/bin/python", "-m", "sapguimcp.server"],
            "enabled": true,
            "environment": {
                "BACKEND_TYPE": "webgui",
                "BROWSER_MODE": "launch",
                "BROWSER_HEADLESS": "true",
                "SAP_HOST": "https://your-sap-server:44300",
                "SAP_USER": "your_username",
                "SAP_PASSWORD": "your_password",
                "SAP_CLIENT": "100",
                "SAP_LANGUAGE": "EN"
            },
            "timeout": 120000
        }
    }
}

WSL users: Use the Linux venv path (e.g. /home/user/sapgui.mcp/.venv/bin/python). Make sure Playwright + Chromium are installed: playwright install chromium

Browser modes:

BROWSER_MODE=launch — Playwright launches and manages Chrome automatically (recommended)
BROWSER_MODE=connect — Connect to an existing Chrome with remote debugging enabled

Connecting to existing Chrome (connect mode)

Start Chrome with remote debugging:

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

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

Then use these env vars instead:

{
    "BACKEND_TYPE": "webgui",
    "BROWSER_MODE": "connect",
    "CDP_URL": "http://localhost:9222"
}

WSL connecting to Windows Chrome:

{
    "BACKEND_TYPE": "webgui",
    "BROWSER_MODE": "connect",
    "CDP_URL": "http://$(hostname).local:9222"
}

Step 3: Start Using

Restart your AI client and try:

"Log me into SAP"
"Run transaction SE16"
"Take a screenshot of the current SAP screen"

Multi-System Access

Add multiple systems to systems.json and switch between them:

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

The AI agent uses sap_login(system_key="qa") to connect to a specific system.

Available Tools

Core SAP Tools

Tool	Description
`sap_login`	Log into SAP (WebGUI: opens login page; Desktop: connects via SAP Logon)
`sap_transaction`	Enter and execute a transaction code
`sap_list_connections`	List configured SAP systems and SAP Logon entries
`sap_screenshot`	Take a screenshot of the current SAP screen
`sap_keepalive_start`	Prevent session timeout (pings every 5 minutes)
`sap_keepalive_stop`	Stop the keepalive task
`sap_get_capabilities`	Query which features the current backend supports

Screen Interaction Tools

Tool	Description
`sap_get_screen_text`	Get all readable text from the current screen
`sap_get_screen_info`	Get technical screen info (program, dynpro, title)
`sap_get_form_fields`	Get all form fields and their current values
`sap_fill_form`	Fill multiple form fields at once
`sap_set_field`	Set a single field by selector or label
`sap_set_checkbox`	Toggle a checkbox
`sap_set_radio_button`	Select a radio button
`sap_click_button`	Click a button by label text
`sap_select_tab`	Select a tab by label text
`sap_select_dropdown`	Select a dropdown option by label and value
`sap_press_key`	Send keyboard shortcuts (F-keys, Ctrl+S, etc.)
`sap_close_popup`	Close modal popups and dialogs
`sap_read_status_bar`	Read status bar messages
`sap_read_table`	Read data from ALV grids and tables
`sap_click_table_cell`	Click a cell in an ALV grid table
`sap_session_status`	Check SAP session status
`sap_lookup_fields`	Look up known field selectors for a transaction
`sap_discover_fields`	Discover input fields on current screen
`sap_discover_buttons`	Discover available buttons on current screen
`sap_get_shortcuts`	Get available keyboard shortcuts

Transaction-Specific Tools

Tool	Description
`sap_se09_lookup`	Search transports (SE09/SE10)
`sap_se11_lookup`	Look up Data Dictionary objects (tables, structures, data elements)
`sap_se16_query`	Query table contents via SE16/SE16N
`sap_se24_lookup`	Look up ABAP class definitions
`sap_se24_edit`	Edit ABAP class source code
`sap_se37_lookup`	Look up function module definitions
`sap_se37_edit`	Edit function module source code
`sap_se38_edit`	Edit ABAP report source code
`sap_se93_lookup`	Look up transaction code definitions
`sap_slg1_lookup`	Query application logs (SLG1)
`sap_sm30_lookup`	Display/maintain table views (SM30)
`sap_sm37_lookup`	Search background jobs (SM37)
`sap_spro_search`	Search customizing activities (SPRO)
`sap_st22_lookup`	Look up ABAP short dumps
`sap_quick_report`	Run SAP Quick Reports (SQVI)

Session Management Tools (Desktop backend only)

Tool	Description
`sap_session_list`	List all active SAP sessions
`sap_session_bind`	Bind to a specific SAP session (for parallel agents)
`sap_session_release`	Release a bound session
`sap_session_close`	Close an SAP session
`sap_session_reset_to_primary`	Reset to primary session

Desktop COM Tools (Desktop backend only)

Tool	Description
`sap_com_snapshot`	Dump the SAP GUI control tree (object hierarchy)
`sap_com_evaluate`	Execute raw COM operations on SAP GUI objects
`sap_run_script`	Run a sandboxed Python script against the SAP GUI COM API
`sap_tree_context_menu`	Open and interact with tree context menus

Catalog Search Tools (offline, no SAP connection needed)

Tool	Description
`search_transactions`	Search bundled transaction catalog by keyword
`search_tables`	Search bundled SAP table catalog by keyword
`search_classes`	Search bundled ABAP class catalog
`search_function_modules`	Search bundled function module catalog

Browser Tools (WebGUI backend only)

Tool	Description
`browser_screenshot`	Capture a PNG of the current SAP Web GUI view
`browser_snapshot`	Get the accessibility tree of the current page
`browser_click`	Click an element by selector
`browser_fill`	Fill an input field
`browser_navigate`	Navigate to a URL
`browser_evaluate`	Execute JavaScript on the page

Configuration Reference

Environment Variables

Variable	Required	Description	Default
`BACKEND_TYPE`	No	`webgui` (browser) 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	`~/.config/sap-mcp/systems.json`
`BROWSER_MODE`	No	`connect` (existing Chrome) or `launch` (Playwright manages Chrome)	`connect`
`BROWSER_TYPE`	No	`chromium`, `firefox`, or `webkit` (WebGUI only)	`chromium`
`BROWSER_HEADLESS`	No	Run browser headless (WebGUI only)	`false`
`CDP_URL`	When `BROWSER_MODE=connect`	Chrome DevTools Protocol URL (WebGUI only)	`http://localhost:9222`
`CHROME_PATH`	No	Explicit path to Chrome binary (WebGUI only)	auto-detect
`COM_MIN_INTERVAL_MS`	No	Min ms between COM calls (Desktop only)	`100`
`LOG_LEVEL`	No	`DEBUG`, `INFO`, `WARNING`, or `ERROR`	`INFO`
`LOG_FORMAT`	No	Set to `json` for JSON log output	`""` (human-readable)

Development Setup

git clone <your-fork-url>
cd sapgui.mcp
pip install -e ".[dev]"
playwright install chromium  # for WebGUI mode

# Run tests
tox -e unit_tests

# Run the server locally
BACKEND_TYPE=desktop run-sapgui-mcp-server

Publishing

See PUBLISHING.md for how to build and publish to PyPI.

./scripts/publish-to-pypi.sh        # publish to PyPI
./scripts/publish-to-pypi.sh --test  # test on TestPyPI first

Architecture

Desktop Backend (BACKEND_TYPE=desktop, Windows only):

AI Client → MCP (stdio) → sapguimcp → COM (pywin32) → SAP GUI for Windows

WebGUI Backend (BACKEND_TYPE=webgui, all platforms):

AI Client → MCP (stdio) → sapguimcp → Playwright → Chrome → SAP Web GUI

Credits

This project is a fork of sapgui.mcp by Hochfrequenz Unternehmensberatung GmbH, released under the MIT License.

Key dependencies from the same team:

sapsucker — Typed SAP GUI Scripting wrapper
sap-mcp-config — Shared SAP system credentials config

License

MIT — see LICENSE for details.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

1.0.1

Jun 17, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ktern_sapguimcp-1.0.1.tar.gz (906.0 kB view details)

Uploaded Jun 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ktern_sapguimcp-1.0.1-py3-none-any.whl (587.3 kB view details)

Uploaded Jun 17, 2026 Python 3

File details

Details for the file ktern_sapguimcp-1.0.1.tar.gz.

File metadata

Download URL: ktern_sapguimcp-1.0.1.tar.gz
Upload date: Jun 17, 2026
Size: 906.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.7

File hashes

Hashes for ktern_sapguimcp-1.0.1.tar.gz
Algorithm	Hash digest
SHA256	`68e2527c80b5720a6efc6690f6a7e1f7d858b75840259b72e47a29081e934637`
MD5	`904bf96bf3dde04a8ad04f407a5f82af`
BLAKE2b-256	`2094085fca11a4b955713cab8022f07cea04df7a6f90534f532c20f758b90760`

See more details on using hashes here.

File details

Details for the file ktern_sapguimcp-1.0.1-py3-none-any.whl.

File metadata

Download URL: ktern_sapguimcp-1.0.1-py3-none-any.whl
Upload date: Jun 17, 2026
Size: 587.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.7

File hashes

Hashes for ktern_sapguimcp-1.0.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`48e6e42abf76efe81876dd455d82e8e219836529026e8599b44c113c1012b557`
MD5	`b556d89ab22601cbd50def03fd36c725`
BLAKE2b-256	`0d5d453927e8b07b74e6dcbe926e28100bb06ff47e6d300e5677bfdd2fe5265f`

See more details on using hashes here.

ktern-sapguimcp 1.0.1

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

KTern SAP GUI MCP Server

Quick Start (uvx)

Prerequisites

Setup

Step 1: Create systems.json

Step 2: Configure Your MCP Client

Desktop Mode (SAP GUI COM — Windows only)

WebGUI Mode (Browser — all platforms)

Step 3: Start Using

Multi-System Access

Available Tools

Core SAP Tools

Screen Interaction Tools

Transaction-Specific Tools

Session Management Tools (Desktop backend only)

Desktop COM Tools (Desktop backend only)

Catalog Search Tools (offline, no SAP connection needed)

Browser Tools (WebGUI backend only)

Configuration Reference

Environment Variables

Development Setup

Publishing

Architecture

Credits

License

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

Step 1: Create `systems.json`