Metadata-Version: 2.4
Name: ktern-sapguimcp
Version: 1.0.1
Summary: MCP server for SAP GUI automation (KTern.AI fork)
Project-URL: Changelog, https://github.com/KaarProducts/ktern-sapguimcp/releases
Project-URL: Homepage, https://ktern.ai
Author-email: "KTern.AI" <engineering@ktern.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: automation,browser,desktop,ktern,mcp,playwright,sap,webgui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: fastmcp[apps]<4.0.0,>=3.2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: sap-mcp-config>=0.1.0
Requires-Dist: sapsucker>=0.6.1
Provides-Extra: build-executable
Requires-Dist: pyinstaller==6.20.0; extra == 'build-executable'
Provides-Extra: coverage
Requires-Dist: coverage==7.14.1; extra == 'coverage'
Provides-Extra: dev
Requires-Dist: pip-tools; extra == 'dev'
Requires-Dist: uv; extra == 'dev'
Provides-Extra: formatting
Requires-Dist: black==26.5.1; extra == 'formatting'
Requires-Dist: isort==8.0.1; extra == 'formatting'
Provides-Extra: linting
Requires-Dist: pylint==4.0.5; extra == 'linting'
Provides-Extra: packaging
Requires-Dist: build==1.5.0; extra == 'packaging'
Requires-Dist: twine==6.2.0; extra == 'packaging'
Provides-Extra: spell-check
Requires-Dist: codespell==2.4.2; extra == 'spell-check'
Provides-Extra: tests
Requires-Dist: anyio==4.13.0; extra == 'tests'
Requires-Dist: beautifulsoup4==4.14.3; extra == 'tests'
Requires-Dist: lxml==6.1.1; extra == 'tests'
Requires-Dist: pytest==9.0.3; extra == 'tests'
Requires-Dist: python-dotenv>=1.0.0; extra == 'tests'
Requires-Dist: respx==0.23.1; extra == 'tests'
Provides-Extra: type-check
Requires-Dist: mypy[pydantic]==2.1.0; extra == 'type-check'
Requires-Dist: types-pyyaml==6.0.12.20260518; extra == 'type-check'
Description-Content-Type: text/markdown

# KTern SAP GUI MCP Server

An MCP (Model Context Protocol) server for SAP GUI automation, maintained by [KTern.AI](https://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](https://github.com/Hochfrequenz/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`:

```bash
uvx ktern-sapguimcp
```

### Prerequisites

1. **uv** installed ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
2. **SAP credentials** configured in `~/.config/sap-mcp/systems.json`
3. **For Desktop mode:** SAP GUI for Windows with scripting enabled (Windows only)
4. **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)

```json
{
    "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`:

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

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

```json
"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).

<details>
<summary><strong>uvx (recommended)</strong></summary>

**Kiro / Claude Code** — `.kiro/settings/mcp.json` or `.mcp.json`:
```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`:
```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`:
```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"
            }
        }
    }
}
```
</details>

<details>
<summary><strong>Local run (from source / venv)</strong></summary>

**Kiro / Claude Code** — `.kiro/settings/mcp.json` or `.mcp.json`:
```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`:
```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.
</details>

**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.

<details>
<summary><strong>uvx (recommended)</strong></summary>

**Kiro / Claude Code** — `.kiro/settings/mcp.json` or `.mcp.json`:
```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`:
```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`:
```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"
            }
        }
    }
}
```
</details>

<details>
<summary><strong>Local run (from source / venv)</strong></summary>

**Kiro / Claude Code** — `.kiro/settings/mcp.json` or `.mcp.json`:
```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`:
```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`
</details>

**Browser modes:**
- `BROWSER_MODE=launch` — Playwright launches and manages Chrome automatically (recommended)
- `BROWSER_MODE=connect` — Connect to an existing Chrome with remote debugging enabled

<details>
<summary><strong>Connecting to existing Chrome (connect mode)</strong></summary>

Start Chrome with remote debugging:
```bash
# 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:
```json
{
    "BACKEND_TYPE": "webgui",
    "BROWSER_MODE": "connect",
    "CDP_URL": "http://localhost:9222"
}
```

**WSL connecting to Windows Chrome:**
```json
{
    "BACKEND_TYPE": "webgui",
    "BROWSER_MODE": "connect",
    "CDP_URL": "http://$(hostname).local:9222"
}
```
</details>

### 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:

```json
{
    "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

```bash
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](PUBLISHING.md) for how to build and publish to PyPI.

```bash
./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](https://github.com/Hochfrequenz/sapgui.mcp) by [Hochfrequenz Unternehmensberatung GmbH](https://github.com/Hochfrequenz), released under the MIT License.

Key dependencies from the same team:
- [sapsucker](https://github.com/Hochfrequenz/sapsucker) — Typed SAP GUI Scripting wrapper
- [sap-mcp-config](https://github.com/Hochfrequenz/sap-mcp-config) — Shared SAP system credentials config

## License

MIT — see [LICENSE](LICENSE) for details.
