📌Overview

Purpose: To provide a Model Context Protocol server that enables automation of interactions with SAP GUI for greater programmatic control over SAP transactions.

Overview: The MCP SAP GUI Server is designed to facilitate automated interaction with SAP GUI, enhancing the efficiency of SAP transaction handling through programmatic methods. It integrates seamlessly with standard development setups involving Python, Node.js, and SAP credentials.

Key Features:

Transaction Management: Tools like launch_transaction and end_transaction allow users to initiate and complete SAP transactions programmatically.
Interface Interaction: Features such as sap_click, sap_move_mouse, and sap_type enable precise UI interactions by specifying exact coordinates and inputs, allowing for automation of repetitive tasks.
Screenshot Management: The server supports various screenshot return formats, including saving images to files, encoding them as base64, or returning them in image content formats, which helps users verify interactions visually.

MCP SAP GUI Server

A Model Context Protocol (MCP) server for SAP GUI automation. This server provides tools to automate interactions with SAP GUI, enabling programmatic control of SAP transactions.

Requirements

Python 3.8 or higher
SAP GUI installed and configured
Valid SAP credentials (system, client, user, password)
Node.js (for npx)

Installation

Clone the repository and run the automated install using the setup script:

setup.bat

This will guide you through the build process and integrate the server directly into Cline or Roo, if selected.

OR manual install using the build script:

build.bat

Configure SAP credentials:

Copy .env.example to .env
Update the values with your SAP credentials

Test server using MCP inspector:

run.bat debug

Use the integration script to automatically configure MCP settings:

integrate.bat cline  # Configure for Cline
integrate.bat roo    # Configure for Roo

The script will:

Automatically determine the correct settings file path
Create a backup before making any changes
Safely update the MCP configuration
Validate changes to prevent corruption

Manual Configuration (if needed):

{
  "mcp-sap-gui": {
    "command": "python",
    "args": [
      "-m",
      "sap_gui_server.server"
    ],
    "cwd": "PATH_TO_YOUR_FOLDER/mcp-sap-gui",
    "disabled": false,
    "autoApprove": []
  }
}

Use this prompt to explain the tool to your AI model:

**Important Safety Notice:**
SAP is a highly sensitive system where incorrect interactions can have serious consequences. Every action must be performed with utmost precision and care. When in doubt about any action, STOP immediately and request user assistance.

**Available Tools:**
The `mcp-sap-gui` server provides tools for SAP GUI interaction:
* `launch_transaction`: Start a new transaction
* `sap_click`: Click at specific coordinates
* `sap_move_mouse`: Move mouse to coordinates
* `sap_type`: Enter text into fields
* `end_transaction`: Close the current transaction

**Technical Limitations and Requirements:**
1. You will receive only screenshot images of the SAP GUI window after each action
2. No direct access to screen element metadata or technical representation
3. You must use image recognition to:
   * Identify UI elements (fields, buttons, etc.)
   * Determine precise x/y coordinates for interactions
   * Verify element sizes and positions
4. All coordinates must be exact - approximate clicking is not acceptable

**Step-by-Step Process:**
1. Start SAP GUI Session:
   * Call `launch_transaction` with desired transaction code
   * Analyze the returned screenshot carefully
2. Interact with Screen:
   * Use image recognition to identify needed elements
   * Calculate exact coordinates for interaction
   * Execute appropriate action (`sap_click`, `sap_type`, etc.)
   * Verify result in next screenshot
3. Capture Screenshots:
   * Save screenshots at key points in the process
4. End Session:
   * Call `end_transaction` when finished

**Best Practices:**
1. Always verify screen state before any action
2. Double-check coordinates before clicking
3. Document each step with clear annotations
4. If uncertain about any element position, request user verification
5. Maintain consistent screenshot naming convention

Available Tools

The MCP SAP GUI Server provides the following tools for SAP automation:

Transaction Management

launch_transaction: Launch a specific SAP transaction code
end_transaction: End the current SAP transaction

Interface Interaction

sap_click: Click at specific coordinates in the SAP GUI window
sap_move_mouse: Move mouse cursor to specific coordinates
sap_type: Type text at the current cursor position
sap_scroll: Scroll the SAP GUI screen (up/down)

Screen Capture

save_last_screenshot: Save the last captured screenshot of the SAP GUI window. Returns the absolute file path of the saved image.

Screenshot Return Formats

All tools that interact with the SAP GUI window (launch_transaction, sap_click, sap_move_mouse, sap_type, sap_scroll) support different screenshot return formats controlled by the return_screenshot parameter:

none (Default): Only returns success/error messages

{
  "type": "text",
  "text": "Status: success"
}

as_file: Saves screenshot to the specified target folder and returns the path

{
  "type": "text",
  "text": "Screenshot saved as C:/path/to/file/screenshot.png"
}

Note: When using as_file, you must specify the target folder using the as_file_target_folder parameter. The folder will be created if it doesn't exist.

as_base64: Returns the raw base64 string

{
  "type": "text",
  "text": "base64_encoded_string_here"
}

as_imagecontent: Returns MCP ImageContent object

{
  "type": "image",
  "data": "base64_encoded_string_here",
  "mimeType": "image/png"
}

as_imageurl: Returns embedded resource with data URL

{
  "type": "resource",
  "resource": {
    "uri": "application:image",
    "mimeType": "image/png",
    "text": "data:image/png;base64,..."
  }
}

Example Usage

# Default - no screenshot
result = await client.call_tool("launch_transaction", {
    "transaction": "VA01"
})

# Save to specific folder
result = await client.call_tool("launch_transaction", {
    "transaction": "VA01",
    "return_screenshot": "as_file",
    "as_file_target_folder": "C:/screenshots"
})

# Get base64 string
result = await client.call_tool("launch_transaction", {
    "transaction": "VA01",
    "return_screenshot": "as_base64"
})

Tool Parameter Summary

Tool	Parameter	Type	Default	Description
`launch_transaction`	`transaction`	`string`		SAP transaction code to launch (e.g., VA01, ME21N, MM03)
	`return_screenshot`	`string`	`none`	Screenshot return format (`none`, `as_file`, `as_base64`, `as_imagecontent`, `as_imageurl`)
	`as_file_target_folder`	`string`		Target folder path for saving screenshots when using 'as_file' return format
`sap_click`	`x`	`integer`		Horizontal pixel coordinate (0-1920) where the click should occur
	`y`	`integer`		Vertical pixel coordinate (0-1080) where the click should occur
	`return_screenshot`	`string`	`none`	Screenshot return format
	`as_file_target_folder`	`string`		Target folder path for saving screenshots
`sap_move_mouse`	`x`	`integer`		Horizontal pixel coordinate to move the cursor to
	`y`	`integer`		Vertical pixel coordinate to move the cursor to
	`return_screenshot`	`string`	`none`	Screenshot return format
	`as_file_target_folder`	`string`		Target folder path for saving screenshots
`sap_type`	`text`	`string`		Text to enter at the current cursor position
	`return_screenshot`	`string`	`none`	Screenshot return format
	`as_file_target_folder`	`string`		Target folder path for saving screenshots
`sap_scroll`	`direction`	`string`		Direction to scroll the screen ('up' or 'down')
	`return_screenshot`	`string`	`none`	Screenshot return format
	`as_file_target_folder`	`string`		Target folder path for saving screenshots
`end_transaction`
`save_last_screenshot`	`filename`	`string`		Path where the screenshot will be saved

Development

Running Tests

Test server using MCP inspector (build + debug):

run.bat full

Or use the test suite:
The test suite includes live tests that interact with SAP GUI. Ensure SAP GUI is installed and configured before running tests.

Run tests:

run.bat test server

The test suite includes tests for:

Tool registration
Request handling
Response formatting
Error handling

Project Structure

mcp-sap-gui/
├── src/
│   └── sap_gui_server/
│       ├── __init__.py
│       ├── sap_controller.py  # SAP GUI interaction logic
│       └── server.py          # MCP server implementation
├── tests/
│   ├── __init__.py
│   ├── test_sap_controller.py
│   └── test_server.py
├── build.bat          # Build and test script
├── integrate.bat      # Integration script for Cline/Roo
├── integrate.py       # Python script for safe MCP settings updates
├── requirements.txt   # Production dependencies
└── requirements-dev.txt  # Development dependencies

License

MIT License