mcp-sap-gui

MCP SAP GUI 服务

一个 MCP（Model Context Protocol） 服务，可通过 SAP GUI Scripting API 让 AI 助手与 Windows 版 SAP GUI 交互。

它不依赖特定客户端：只要你的 MCP 客户端能够启动本地 stdio 服务，就可以使用本项目。本 README 中的示例使用 Claude，因为演示配置很简单，但同一服务也可以用于 Codex、GitHub Copilot、Gemini CLI 及其他兼容 MCP 的工具。

当前版本：0.5.4，用于通过 MCP stdio 在 Windows 上本地运行。

状态

• 包含用于 CI、Docs、Dependency Audit 和基于标签的 Release 的 GitHub 工作流。
• 主仓库：GitHub（kts982/mcp-sap-gui）。

最新动态

0.5.4 是针对 HTTP 传输的安全版本：现在会拒绝网页可通过 DNS 重绑定伪造的请求（安全公告）。默认的 stdio 不受影响。此版本还会防止 sap_set_policy_profile 限制在一天后失效，并报告服务自身的版本。按版本查看所有变更：CHANGELOG。

sap_preview — 预先查看操作效果。 Agent 现在可以在任意检查点向你显示审批卡片：批量写入之前、保存之前，或在你提出要求时（“添加国家 GR 之前，先给我看看这些值”）。卡片包含当前截图、会话上下文以及即将写入的确切值——密码形式的值会被遮蔽。在 MCP Apps 宿主（VS Code Copilot Chat）中会以丰富的内嵌卡片呈现；其他情况下则会显示相同的摘要文本和截图。保存操作仍需经过确认门控。详情：预览卡片渲染。

确认点——未经你许可，不会写入任何内容。 只需告诉 Agent 一次（“每次写入字段前都先问我”），服务就会强制执行：sap_set_confirmation_points 会启用各类写入操作的确认机制，在任何内容写入 SAP 前暂停并等待你的明确批准。该机制通过中间件在服务端强制执行——即使 Agent 采取任何操作，拒绝都会阻止调用；移除确认门控前会先征求你的同意；管理员还可以使用 --confirm 为所有会话固定启用确认门控。详情：安全注意事项。

功能说明

此服务可让 AI 助手：

• 连接 SAP 系统（类似于在 SAP Logon Pad 中双击）
• 执行事务（MM03、VA01、/SCWM/MON 等）
• 读取和写入屏幕字段、复选框、单选按钮、组合框和选项卡
• 使用 F4 值帮助：命中列表、限制对话框、日期和时间选择器
• 从菜单栏选择菜单项（Table View、Edit、Selection 等）
• 使用键盘按键和按钮在 SAP 屏幕间导航
• 从 ALV 网格（GuiGridView）和经典表格控件（GuiTableControl）提取数据
• 将经典报表列表（WRITE 输出）作为文本读取，包括行的颜色
• 与 ALV 工具栏按钮和上下文菜单交互
• 读取树形控件（TableTree、ColumnTree、SimpleTree）并与之交互，包括视图集群的停靠式对话框结构
• 对 SAP 窗口截图，可内嵌显示或保存为全分辨率文件
• 发现屏幕元素以用于自动化
• 在写入前显示预览，并在你选择的确认点暂停以等待批准

示例对话

User: "What's the description for material MAT-001 in system D01?"

Assistant: [connects to D01]
           [executes MM03]
           [enters material number]
           [reads description field]

"The material MAT-001 is described as 'High-Grade Steel Plate 10mm'
in system D01."

快速开始

1. 安装 uv（它附带 uvx），如果尚未安装：

pip install uv

2. 启动 SAP Logon Pad 并打开 SAP GUI 会话，或至少确保 SAP Logon 正在运行。

3. 配置 MCP 客户端以启动此服务。无需克隆或手动安装——uvx 会从 PyPI 上的已发布软件包获取并在隔离环境中运行：

Command:   uvx
Arguments: mcp-sap-gui[screenshots]
Transport: stdio

（如果你正在使用源码检出版本，请参阅安装。）

4. 尝试以下提示词之一：

Connect to my open SAP session and tell me what system I'm on
Show me the current screen info
List all editable fields on this screen
Read the first 20 rows of the visible table

sap_connect 有意不接受密码参数。更安全的做法是先通过 SAP GUI 登录，然后使用 sap_connect_existing 连接现有会话。

要求

• Windows（SAP GUI 仅在 Windows 上运行）
• 已安装 SAP GUI for Windows
  • 已验证与 SAP GUI for Windows 8.10 64-bit Patch 0 的实时兼容性。SAP 对 8.10 的支持截至 2029 年 6 月 30 日，对 8.00 的支持截至 2027 年 1 月 12 日（受限支持截至 2027 年 7 月 31 日）；7.70 及更早版本已不在 SAP 支持范围内，将尽力提供支持。日期、来源以及各功能所需版本：SAP GUI 版本
  • 7.70 Patch Level 3 或更高版本可通过一次调用（GetObjectTree）读取整个屏幕、弹出窗口、列表页或表格控件；更早版本会退回到逐个读取元素，在大型屏幕上速度慢得多（读取完整列表页需要数秒，而不是不到一秒）
• SAP Logon Pad 正在运行，或由 SAP Business Client（实验性，见下文）或其他嵌入式 SAP GUI 承载的 SAP GUI 会话（用于 COM 连接）
• SAP 系统已启用 SAP GUI 脚本
• Python 3.10+
• uv（推荐的 Python 包管理器）

SAP Business Client（实验性）

• SAP Business Client 中的经典事务运行于嵌入式 SAP GUI for Windows，因此仍需设置服务端脚本参数。sapgui/nwbc_scripting 提供只读脚本功能（效果等同于 sapgui/user_scripting + sapgui/user_scripting_set_readonly）：写入工具会拒绝执行，且无法滚动网格，因此表格读取会在屏幕上显示的行处停止。
• 会话通过 SAP GUI 服务进程的 COM Running Object Table 项（SAPGUISERVER-<pid>）发现，与通常的 SAP Logon 项并列。sap_list_connections 会为这些会话报告 host: "sapguiserver"。
• 一个 Business Client 窗口中的多个标签页属于同一连接的会话；第二个系统则是第二个连接。
• Business Client 连接没有 SAP Logon 描述；列表会显示系统和客户端（例如 DEV (100)）。
• 反复按 Back 会关闭标签页，而不是返回 SAP Easy Access 菜单（SAP Business Client FAQ）。
• Fiori Launchpad 连接可能会将事务渲染为 SAP GUI for HTML；此类事务无法通过脚本访问。

支持范围

支持：

• 通过 SAP GUI Scripting COM API 使用 SAP GUI for Windows
• MCP stdio（默认）和 streamable HTTP 传输
• 按客户端隔离会话（多个 MCP 客户端可持有各自独立的 SAP 会话）
• 在兼容 MCP 的客户端中交互使用
• 在已登录 SAP 用户的权限范围内，对 SAP GUI 进行读写自动化

暂不支持：

• SAP GUI for Java 或 SAP GUI for HTML
• 基于浏览器的 Fiori 自动化
• 无人值守的多用户生产环境编排

启用 SAP GUI 脚本

必须同时在客户端和服务端启用 SAP GUI 脚本：

客户端（SAP GUI 选项）：

1. 打开 SAP GUI → Options → Accessibility & Scripting → Scripting
2. 勾选“Enable scripting”
3. 可选：取消勾选“Notify when a script...”，以实现更流畅的自动化

服务端（SAP 系统）：

• 事务 RZ11 → 参数 sapgui/user_scripting → 设置为 TRUE
• 需要 SAP Basis 管理员权限

在脚本受到限制的环境中部署

许多组织默认在全局范围禁用 SAP GUI Scripting，以加强安全性。启用它不必非此即彼：SAP 提供了分级的服务端控制，让 Basis 团队可以谨慎地启用脚本——通常仅限开发系统上的指定用户，同时对其他所有用户保持禁用。

配置参数（RZ11/RZ10）	作用
sapgui/user_scripting = TRUE	总开关；任何脚本功能都必须启用此项
sapgui/user_scripting_per_user = TRUE	只有持有授权对象 S_SCR（类别 BC_A，活动 16）的用户才能使用脚本功能；其他所有用户仍会被阻止（SAP Note 983990）
sapgui/user_scripting_set_readonly = TRUE	脚本可以读取屏幕状态，但不能发送任何会改变服务端状态的内容（SAP Note 692245）
sapgui/user_scripting_force_notification = TRUE	脚本连接时，用户始终会看到通知／同意对话框；无法在本地 SAP GUI 选项中禁用（SAP Note 3591984）
sapgui/user_scripting_disable_recording = TRUE	禁止录制新脚本；仍可播放脚本

向 Basis／安全团队提出此方案时，可参考以下要点：

• 自 SAP GUI 7.40 PL17 / 7.50 PL4 起，按用户启用和只读模式可以组合使用：S_SCR 持有者可使用完整 API，其他用户则为只读（SAP Note 2565390）。
• 在只读会话中，此服务会在会话信息中报告 scripting_read_only: true，并在执行前拒绝所有写入工具，同时说明原因，而不是让每个操作都在 SAP GUI 内部失败。所有读取工具仍可正常使用。
• 通过 RZ11 对 sapgui/user_scripting 所做的动态更改不会持久生效——下次应用服务器重启时会恢复原值，因此适合在开发系统上进行限时评估。
• 在服务端，脚本化操作会使用 SAP 用户的常规授权运行，并在日志中显示为普通用户活动。用户的授权配置文件是实际的安全边界——可搭配专用的最小授权账户，以及此服务的事务策略选项（--policy-preset、--policy-file）、--profile 和 --audit-log，实现纵深防御。
• 权威参考资料：SAP GUI Scripting 安全指南（help.sap.com）。

**为什么必须使用 Scripting API：**适用于 Windows 的 SAP GUI 会在自定义画布上绘制 dynpro 屏幕，Windows UI Automation 或其他辅助功能 API 无法从中获取可用的结构化信息——Scripting API 是读取和操作 SAP GUI 屏幕的唯一结构化方式。商业 RPA 产品也存在相同依赖；禁用脚本功能时，它们会退回到基于屏幕截图／OCR 的自动化方式。本项目有意避免这种方式，因为它不精确且脆弱。

安装

从 PyPI 安装（推荐用户使用）

无需克隆。首次启动时，uvx 会下载最新版本并在隔离环境中运行：

# Smoke test the published package
uvx "mcp-sap-gui[screenshots]" --help

[screenshots] 附加组件可优化屏幕截图（将截图大小减少 70-90%），建议启用。它需要 Python 3.11 或更高版本；在 3.10 上不会安装任何内容，截图也不会经过优化。将 MCP 客户端指向 uvx，并将 mcp-sap-gui[screenshots] 设为参数——请参阅下文的 MCP 配置。

**更新到新版本：**首次启动后，uvx 会继续使用已缓存的版本，因此不会自动获取新版本。运行一次 uvx "mcp-sap-gui[screenshots]@latest" --help，然后重启 MCP 客户端；客户端下次启动时就会使用新版本。若要固定使用某个版本，请将版本号写入客户端参数：mcp-sap-gui[screenshots]==<version>。

从源代码运行（用于开发）

# Clone the repository
git clone https://github.com/kts982/mcp-sap-gui.git
cd mcp-sap-gui

# Install uv (if not already installed)
pip install uv

# Install all dependencies (creates .venv automatically)
uv sync

# With screenshot optimization (recommended - reduces screenshot size by 70-90%)
uv sync --extra screenshots

# With dev dependencies (for testing, linting, type checking)
uv sync --extra dev --extra screenshots

**Windows 源代码检出注意事项：**从此检出目录启动的 MCP 服务运行时，其进程会锁定 .venv 中的原生 DLL（pywin32、watchfiles）。此时运行 uv sync 或升级依赖可能会失败并显示“Access is denied”，也可能导致 .venv 只更新了一部分——请先停止或重启 MCP 客户端，再进行同步。如果两个 MCP 客户端（例如 Claude Code 和 VS Code）从同一检出目录启动服务，请让第二个客户端使用隔离环境，而不是共享的 .venv：

Command:   uv
Arguments: run --isolated --no-project --with "mcp-sap-gui[screenshots,apps] @ file:///<path-to-checkout>" python -m mcp_sap_gui.server

（uvx mcp-sap-gui 用户不受影响——每次 uvx 启动都会使用独立的缓存环境。）

用法

连接建议：对于已完成身份验证的会话，优先使用 sap_connect_existing。sap_connect 主要用于 SSO 流程，或在用户手动登录前打开 SAP 登录界面。

直接运行 MCP 服务

# Standard mode (stdio, default)
uv run python -m mcp_sap_gui.server

# Read-only mode (safer for exploration)
uv run python -m mcp_sap_gui.server --read-only

# With transaction whitelist
uv run python -m mcp_sap_gui.server --allowed-transactions MM03 VA03 ME23N

# HTTP transport (binds to 127.0.0.1). Requests addressed to another host
# name (DNS rebinding) or sent by a web page from another origin are refused.
uv run python -m mcp_sap_gui.server --transport http

# HTTP on another address: name the host clients use for this machine
# (--allowed-origin adds a browser origin that may call the server)
uv run python -m mcp_sap_gui.server --transport http --host 0.0.0.0 --port 9000 --allowed-host sap-box

# Policy profile (restrict visible tools)
uv run python -m mcp_sap_gui.server --profile exploration

# Confirmation points (ask the user before these categories run, every session)
uv run python -m mcp_sap_gui.server --confirm field_writes transactions

# Audit log to file (JSON lines)
uv run python -m mcp_sap_gui.server --audit-log sap_audit.jsonl

# On shutdown, leave every SAP session open, even the ones sap_connect opened
uv run python -m mcp_sap_gui.server --detach-on-exit

# EXPERIMENTAL: code mode — replaces the tool catalog with search/get_schema/
# tags/execute meta-tools; agents script chained SAP flows in a sandbox.
# Faster and cheaper on long chained flows (e.g. full table dumps), slower on
# quick one-shot questions. Requires: uv sync --extra code-mode
uv run --extra code-mode python -m mcp_sap_gui.server --code-mode

# Same, from the published PyPI package (no checkout needed)
uvx "mcp-sap-gui[screenshots,code-mode]" --code-mode

# Debug mode
uv run python -m mcp_sap_gui.server --debug

MCP 配置

此服务通过 stdio（stdin/stdout JSON-RPC）通信，这是标准的 MCP 传输方式。无需配置端口或 URL——MCP 客户端会启动服务进程，并直接与其通信。

对于任何客户端，核心启动配置都相同：

Command:   uvx
Arguments: mcp-sap-gui[screenshots]
Transport: stdio

要从源代码检出目录运行，而非从 PyPI 运行？请使用 uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server 作为命令。

客户端配置链接

• Claude Code / Claude Desktop：下文包含配置示例
• Codex：在 Codex 中配置 MCP 服务，并将其指向上述命令。官方 MCP 文档：https://developers.openai.com/learn/docs-mcp
• GitHub Copilot：在 Copilot Chat / Agent 模式下配置本地 MCP 服务。官方文档：https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp
• Gemini CLI：在 Gemini CLI 设置中的 mcpServers 下添加服务。官方文档：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

以下是最常见的本地 SAP GUI 配置方式的完整示例。

按客户端分类的配置指南请参见 docs/CLIENTS.md。

---

选项 1：Claude Code（推荐用于开发）

此仓库在项目根目录中包含 .mcp.json。在 Claude Code 中打开此项目时，系统会自动发现 MCP 服务——无需手动配置。

使用方法：

cd mcp-sap-gui
claude

Claude Code 会检测 .mcp.json 并自动启动 SAP GUI MCP 服务。

如果要在 Claude Code 中进行全局配置（在任何项目中均可用），请将其添加到用户设置文件 ~/.claude/.mcp.json：

{
  "mcpServers": {
    "sap-gui": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]"]
    }
  }
}

---

选项 2：Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

标准模式：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]"]
    }
  }
}

**注意：**要从源代码检出目录运行，而非从 PyPI 运行？请使用 "command": "uv" 和 "args": ["run", "--directory", "<path-to-mcp-sap-gui>", "python", "-m", "mcp_sap_gui.server"] ——必须使用 --directory 标志，这样无论 Claude Desktop 使用哪个工作目录，uv 都能找到项目的虚拟环境。

只读模式（推荐用于浏览／查询数据）：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots]", "--read-only"]
    }
  }
}

使用事务白名单（仅允许特定事务）：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": [
        "mcp-sap-gui[screenshots]",
        "--allowed-transactions", "MM03", "VA03", "ME23N"
      ]
    }
  }
}

编辑配置后，重启 Claude Desktop 使更改生效。

---

选项 3：任何兼容 MCP 的客户端

此服务使用 stdio 传输。将任何 MCP 客户端指向：

Command:   uvx mcp-sap-gui[screenshots]
Arguments: [--read-only] [--profile exploration|operator|full] [--confirm POINT ...] [--audit-log FILE] [--detach-on-exit] [--debug] [--policy-preset default|abap-dev|strict] [--policy-file FILE] [--allowed-transactions T1 T2 ...]
Transport: stdio

对于源代码检出目录，请改用 uv run --directory <path-to-mcp-sap-gui> python -m mcp_sap_gui.server。

---

验证配置

配置完成后，可以向 Claude 提问，以验证 MCP 服务是否正常运行：

"List all available SAP GUI tools"

Claude 应返回完整的 sap_* 工具列表。如果 SAP GUI 正在运行，请尝试：

"Connect to my open SAP session and tell me what system I'm on"

然后尝试：

"Show me the current screen info"
"List all editable fields on this screen"
"Read the first 20 rows from the visible table"

内置 Agent 指引

服务内置了导航知识，可帮助任何 MCP 客户端（Claude Code、Copilot、Cursor、Cline 等）有效使用 SAP GUI：

• MCP 指令 — 在初始化期间注入每个客户端的系统提示词。涵盖屏幕发现工作流、弹窗处理、表格分页、SPRO 树导航、按键参考以及常见错误。
• docs://sap-gui-guide 资源 — 可通过 resources/read 按需获取的详细参考指南。涵盖元素类型、ID 命名约定、事务代码格式、表格类型对比、状态栏消息，以及 SPRO 和表维护视图的分步操作模式。

这些内容可避免 Agent 犯下常见错误，例如猜测元素 ID、忽略弹窗、想刷新时却按 F5（="新建条目"）、在 SPRO 中使用 double_click_tree_node（这会打开文档，而非执行活动），或在视图集群中使用它（不会产生任何效果），以及从截图中读取经典报表列表，而不是使用 sap_read_list。

可用工具

该服务目前提供 60 个 MCP 工具。

类别	数量	涵盖内容
连接与策略	7	连接 SAP、附加到已打开的会话、检查会话、断开连接、设置策略配置文件、设置确认点
导航	3	执行事务、发送按键、检查当前屏幕
字段与 UI	13	读取/写入字段、按钮、选项卡、组合框、文本编辑框、焦点
表格与网格	17	ALV 网格、TableControls、行选择、列信息、单元格操作
弹窗 / 工具栏 / Shell / 列表	5	检查和处理弹窗、发现工具栏、Shell 内容、经典报表列表
树	10	读取/搜索/展开/选择/单击 SAP 树控件
发现	2	发现屏幕元素和截取屏幕截图
预览	1	向用户展示当前屏幕，以及 Agent 即将写入的值
工作流指引	1	返回已知多工具 SAP 工作流的分步指引
事务指引	1	返回受支持 SAP 事务的通用、先读取后操作指南

最重要的操作模式：

• 使用 sap_get_screen_elements 发现 ID，而不是猜测
• 从任何 SAP 表格/网格开始时，使用 sap_read_table
• 报表输出为普通列表而非 ALV 网格时，使用 sap_read_list
• 每个操作的响应都会在弹窗打开时附带一段简短的 popup 摘要（包括分类、文本、按钮标签，以及 prefilled_inputs，用于提示输入项是否已有值或选项是否已预选）；sap_get_popup_window 会提供完整详情并建议安全的下一步
• 想要让服务只关闭明确安全的信息弹窗，并在其他情况下保持对话框不变时，使用 sap_handle_popup(action="auto")
• 执行重要写入（批量填充字段、F11 / 保存）前使用 sap_preview，让用户先查看屏幕和待写入的值
• 使用 sap_set_confirmation_points，让特定类别的写入在执行前请求用户批准
• 想要了解已知工作流的可靠操作顺序时，使用 sap_get_workflow_guide
• 想要了解受支持事务的通用指南时，使用 sap_get_transaction_guide：/SCWM/MON（也称 warehouse monitor），或用于表/视图维护和视图集群的 SM30（也称 SM34、view cluster）
• 对于 SPRO 风格的导航，使用 sap_read_tree 以及搜索/展开辅助工具

完整工具目录按类别分组并附有简短说明，详见 docs/TOOLS.md。

渲染的预览卡片

sap_preview 为只读工具，始终会返回文字摘要和截图，因此可在所有 MCP 客户端中使用。支持 MCP Apps UI 扩展的客户端（例如 VS Code Copilot）则会显示包含截图和待处理值表格的渲染卡片。安装可选扩展以启用卡片：

uv sync --extra apps          # or: uvx "mcp-sap-gui[screenshots,apps]"

受限或离线网络： 默认情况下，卡片渲染器从 jsDelivr CDN 加载，因此在无法访问外网的工作站上，卡片会静默渲染失败。在服务的环境中设置 PREFAB_BUNDLED_RENDERER=1，即可让渲染器独立运行（约 6.3 MB 的内联资源，不涉及第三方域名）：

{
  "mcpServers": {
    "sap-gui": {
      "command": "uvx",
      "args": ["mcp-sap-gui[screenshots,apps]"],
      "env": { "PREFAB_BUNDLED_RENDERER": "1" }
    }
  }
}

安全注意事项

此服务提供强大的自动化功能。请负责任地使用。

内置防护措施

1. 事务策略 - Agent 可以启动哪些事务。具体哪些事务具有危险性，取决于谁运行服务以及目标系统，因此策略可配置：

   • --policy-preset default（默认值）会阻止用户和角色管理（SU01、SU10、SU01D、PFCG、SU53）、日志和转储（SM21、ST22）、开发和程序执行（SE38、SA38、SE80、SE37、SE16N）以及系统管理（STMS、SCC4、RZ10、RZ11、SM36、SM49、SM69、SM59、STRUST、SICF、SM01、SM18、SM19）。定制和显示操作（SM30、SM34、SPRO、SE16、SE11）不受限制
   • --policy-preset abap-dev 还会允许 SA38、SE11 和 SE80，供开发者测试自己的程序
   • --policy-preset strict 会阻止策略文件未明确允许的所有内容
   • --policy-file policy.json 会在预设基础上添加规则：{"preset": "abap-dev", "block": ["ZHR*"], "allow": ["SM59"]}。条目可以是代码或 glob 模式（SU*、/SCWM/*）；allow 的优先级始终高于 block。未指定此标志时，服务会读取 $MCP_SAP_GUI_POLICY_FILE；如果该变量未设置，则在文件存在时读取 %APPDATA%\mcp-sap-gui\policy.json。请将该文件保存在 Agent 工作区之外
   • examples/ 中附带两个示例：policy.example.json 以 default 为基础，额外阻止客户命名空间（ZHR*）和 SE16，并允许使用 ST22 分析转储；policy.strict.example.json 是仅供显示的 Agent 使用的允许列表。在 Windows 上将其中一个设为每用户策略：New-Item -ItemType Directory -Force "$env:APPDATA\mcp-sap-gui"; Copy-Item examples\policy.example.json "$env:APPDATA\mcp-sap-gui\policy.json"
   • 策略在启动时读取一次，并写入审计日志（包含文件的 SHA-256）。任何工具都无法更改该策略；如果策略文件无法读取，服务会停止，而不会回退到限制更宽松的配置
   • 匹配不区分大小写；会处理 /n、/o、/* 前缀和空白字符
   • 这是防止 Agent 出错的防护措施，不是安全边界：被阻止的事务往往仍可通过其他方式访问（例如菜单路径，或已打开但未关闭的屏幕）。SAP 用户的授权才是安全边界

2. 防止绕过 OK-Code - 如果将 tbar[0]/okcd、txtOK_CODE 等可能的 SAP 命令字段或类似命令代码别名设置为被阻止的事务，也会被阻止，以防绕过事务策略

3. 只读模式 - --read-only 标志会禁用所有修改操作（字段写入、按钮按下、事务执行、按键发送、树和表格交互）

4. 事务允许列表 - 在生产环境中，请使用允许列表：strict 策略预设，并在策略文件中配置 allow 列表（支持 /SCWM/* 等模式）。旧版 --allowed-transactions T1 T2 ... 标志仍可使用，并会在策略限制之外进一步收紧范围。

5. 策略配置文件 - --profile 控制可见的工具：exploration（只读）、operator（读写）、full（全部，默认）。也可以通过 sap_set_policy_profile 按会话切换配置文件——但服务端的 --profile 是权限下限：会话可以进一步收紧权限，但不能授予自己超出服务端允许范围的权限

6. 工具标签 - 每个工具都标记为 read 或 write，以供策略配置文件筛选。所有工具都带有 MCP readOnlyHint/destructiveHint 注释，客户端可据此显示相应的 UI 提示

7. 保存确认 - sap_send_key("F11") 和 sap_send_key("Save") 现在必须通过 MCP elicitation 获得用户明确确认。如果客户端不支持 elicitation，保存操作会被阻止，而不会静默执行。

8. 确认点 - 写入操作的命名类别，服务器执行前必须获得用户的阻塞式审批。save（F11 / Save 键以及 wnd[0]/tbar[0]/btn[11] 保存工具栏按钮）始终启用。transactions、batch_fields、field_writes、all_writes 和 attach 可通过 sap_set_confirmation_points 按会话启用，也可通过 --confirm POINT [POINT ...] 为每个会话启用。attach 是选择项，而非是非题：sap_connect_existing 允许用户选择 Agent 操作的 SAP 会话（--confirm attach 会在每次聊天中启用此项）。

   该门控由服务器端中间件强制执行，因此无论 Agent 执行何种操作都适用——包括在实验性的 --code-mode 沙盒中。添加确认点不会弹出提示；移除会话级确认点则需要先征得用户同意，而通过 --confirm 设置的确认点完全无法移除。用户拒绝后会返回错误，且不会执行任何操作；不支持 elicitation 的客户端会安全失败（被门控的调用会报错，而不是在未经确认的情况下运行）。每次确认都会连同结果（accepted、declined、unsupported_client）写入审计日志。

   客户端必须显示这些提示。Claude Code CLI 支持此功能；Claude Code 桌面应用（测试日期：2026-10-19）则在几毫秒内拒绝了每次提示，却没有显示出来，因此无法在该应用中批准通过服务器执行的保存操作。此时服务器会提示未显示对话框，而不是报告你拒绝了操作。参见确认点。

   不支持 elicitation 的客户端也会在移除确认点时安全失败：在此类客户端中启用的确认点之后无法关闭，因此会在会话剩余时间内阻止该类别的所有操作。确认点在 sap_disconnect 后仍然有效——它们的生命周期是 MCP 会话，而非 SAP 连接。

   all_writes 涵盖所有标记为 write 的工具，包括不会更改业务数据的选择、滚动和导航辅助工具——此配置有意设置得严格且提示频繁；启用后，sap_send_key("F11") 会提示两次（一次针对该类别，一次针对始终启用的保存门控）。

9. 审计日志 - --audit-log FILE 会将每次工具调用（名称、参数、耗时、结果，以及聊天所绑定的 SAP 系统、客户端和用户）以 JSON 行格式写入文件。参数中的机密会自动屏蔽

10. 安全的凭据解析 - sap_connect 会从 .env 文件（SAP_USER、SAP_PASSWORD、SAP_CLIENT、SAP_LANGUAGE）解析凭据。MCP 工具参数中绝不接受密码，密码也不会出现在客户端日志、工具调用历史或审计日志中。复制 .env.example 为 .env 即可开始使用

11. ID 验证与规范化 - 调用 findById() 前，会先验证用户提供的 SAP 窗口和元素 ID。接受 wnd[0]/usr/... 等标准 ID，并会自动将 /app/con[0]/ses[0]/wnd[0]/usr/... 等完整会话路径规范化为短格式。

12. HTTP 主机和来源检查 - 使用 --transport http 时，若请求所指向的主机名不是 localhost、127.0.0.1、绑定地址或 --allowed-host 中列出的主机名，请求就会被拒绝（421）。这样网页就无法将自己的域名指向这台机器（DNS 重绑定）并使用该服务。来自其他来源的浏览器请求也会被拒绝（403），除非该来源列在 --allowed-origin 中；localhost 上的页面视为本地页面。MCP 客户端不会发送 Origin，因此不受影响。默认传输方式 stdio 不涉及网络。

生产环境使用建议

• 切勿向不受信任的用户开放
• 使用只读模式进行探索和查询
• 为自动化操作设置事务白名单
• 在 SAP 端启用审计日志
• 使用授权范围最小的专用服务账户
• 按用户启用脚本，而非全局启用 — 使用 sapgui/user_scripting_per_user 和 S_SCR 授权，将脚本权限限制给指定用户（参见在脚本受限的环境中部署）
• 在隔离系统上运行（测试／沙盒环境，而非生产环境）

SAP 许可

请查阅您的 SAP 许可协议，了解以下事项：

• 自动化访问和脚本
• 间接访问相关事项
• 命名用户许可与并发用户许可

工作流示例

显示物料主数据

# Claude would execute these tools:
sap_connect("D01 - Development System")
sap_execute_transaction("MM03")
sap_set_field("wnd[0]/usr/ctxtRMMG1-MATNR", "MAT-001")
sap_send_key("Enter")
# Select views...
sap_send_key("Enter")
description = sap_read_field("wnd[0]/usr/txtMAKT-MAKTX")

提取采购订单列表

sap_execute_transaction("ME2M")
sap_set_field("wnd[0]/usr/ctxtEN_LIFNR-LOW", "1000")  # Vendor
sap_send_key("Execute")  # F8
data = sap_read_table("wnd[0]/usr/cntlGRID1/shellcont/shell", max_rows=50)

导航至销售订单

sap_execute_transaction("VA03")
sap_set_field("wnd[0]/usr/ctxtVBAK-VBELN", "12345")
sap_send_key("Enter")
# Read header data
customer = sap_read_field("wnd[0]/usr/subSUBSCREEN.../txtVBAK-KUNNR")
# Navigate to items
sap_press_button("wnd[0]/usr/tabsTAXI_TABSTRIP.../tabpT\\01")
items = sap_read_table("wnd[0]/usr/.../cntlGRID1/shellcont/shell")

筛选自定义配置表（GuiTableControl）

# In SPRO or SM30 table maintenance view
# Use Selection -> By Contents to filter
sap_select_menu("wnd[0]/mbar/menu[3]/menu[0]")    # Selection > By Contents
# Select the field to filter on, enter value
sap_select_table_row("wnd[1]/usr/tblSAPLSVIXTCTRL_SEL_FLDS", 0)
sap_send_key("Enter")
sap_set_field("wnd[1]/usr/.../txtQUERY_TAB-BUFFER[3,0]", "EXTSYS001")
sap_send_key("Execute")
# Read the filtered table
data = sap_read_table("wnd[0]/usr/tblSAPLBD41TCTRL_V_TBDLS")

批量填写并验证表单

sap_set_batch_fields(
    {
        "wnd[0]/usr/ctxtFIELD1": "VALUE1",
        "wnd[0]/usr/txtFIELD2": "VALUE2",
    },
    validate=True,
    skip_readonly=True,
)
# Returns per-field results plus post-Enter screen feedback

向用户展示即将进行的更改

“添加国家/地区 GR 之前，先向我展示这些值。”

# Read-only: renders the current screen plus the pending values.
sap_preview(
    note="About to add country GR to V_T005",
    pending_fields={
        "Country Key (V_T005-LAND1)": "GR",
        "Name": "Greece",
        "Currency": "EUR",
    },
)
# The user confirms in chat, then the agent writes and saves:
sap_set_batch_fields({...}, validate=True)
sap_send_key("Save")   # still requires explicit confirmation via elicitation

项目结构

mcp-sap-gui/
├── docs/
│   ├── CLIENTS.md             # Client-specific MCP setup notes
│   ├── OVERVIEW.md            # Product overview and roadmap direction
│   └── TOOLS.md               # Full MCP tool catalog
├── scripts/
│   └── check_docs.py          # Markdown link checker used by docs workflows
├── src/
│   └── mcp_sap_gui/
│       ├── __init__.py        # Package exports
│       ├── server.py          # MCP server implementation (tool definitions)
│       ├── session_manager.py # Per-client SAP session isolation
│       ├── sap_controller.py  # Facade class (composes all mixins)
│       ├── models.py          # VKey enum, SessionInfo, exceptions
│       ├── controller.py      # Base controller (connection, navigation, screen info)
│       ├── fields.py          # FieldsMixin (read/write fields, buttons, combos)
│       ├── tables.py          # TablesMixin (ALV grid + TableControl operations)
│       ├── trees.py           # TreesMixin (tree read, expand, select, click)
│       ├── discovery.py       # DiscoveryMixin (popups, toolbars, screenshots)
│       ├── confirmation.py    # Confirmation points + blocking-confirmation middleware
│       └── preview.py         # sap_preview text + Prefab card builders
├── tests/
│   ├── test_sap_controller.py # Controller unit tests
│   ├── test_confirmation.py   # Confirmation points: gate, tool, CLI floor
│   ├── test_preview.py        # sap_preview builders + card/text branches
│   └── test_server.py         # Server security & routing tests
├── examples/
│   └── basic_usage.py         # Direct controller example
├── .mcp.json                  # MCP server config (auto-detected by Claude Code)
├── CONTRIBUTING.md            # Contribution guidelines for public changes
├── LICENSE                    # MIT license
├── pyproject.toml
├── uv.lock                    # Dependency lock file (managed by uv)
└── README.md

故障排除

“无法连接到 SAP GUI”

• 确保 SAP Logon Pad、SAP Business Client 或其他 SAP GUI 会话正在运行
• 检查 SAP GUI 选项中是否已启用 SAP GUI Scripting

“脚本已禁用”错误

• sap_list_connections 会通过 scripting_disabled: true 报告此类系统，且不显示会话
• 在服务器端启用脚本：RZ11 → sapgui/user_scripting = TRUE
• 需要 SAP Basis 管理员操作
• 组织不愿全局启用脚本？请参见在脚本受限的环境中部署，了解按用户启用和只读启用选项

“找不到元素”

• 使用 sap_get_screen_elements() 查找可用的字段 ID
• 由于自定义配置，不同 SAP 系统中的字段 ID 可能有所不同

启动时出现 COM 错误

• 确保已安装依赖项：uv sync
• 如果出现 COM 注册问题，请运行 uv run python -m win32com.client.makepy

“我的 MCP 客户端中没有显示 SAP 工具”

• 确认客户端从项目根目录启动服务
• 更改 MCP 配置后，重启 MCP 客户端
• 先运行 uv sync，确保环境和依赖项已就绪

读取时 SAP Logon 退出

• 使用 SAP GUI 8.00 和 0.5.0 时，读取表格控件和经典列表可能导致 SAP Logon 退出：请升级到 0.5.1（issue #22）
• 如果其他 SAP GUI 版本在单次调用读取时发生故障：在相应调用位置通过 MCP_SAP_GUI_DISABLE_OBJECT_TREE 关闭此功能，并使用 MCP_SAP_GUI_TRACE_FILE 查找相关调用。请参见有问题的 SAP GUI 版本的开关

“工具可用，但操作被阻止”

• 检查服务是否以 --read-only 模式运行
• 检查事务策略是否阻止了该操作：错误信息会指出当前使用的预设。可在策略文件中允许该事务（--policy-file，参见安全注意事项），或选择其他 --policy-preset，然后重启服务。无法在会话中更改策略
• 检查启动服务时是否指定了 --allowed-transactions

开发

# Install all dependencies (dev + screenshots)
uv sync --extra dev --extra screenshots

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

相关链接

• SAP GUI Scripting API 文档
• MCP 规范
• 贡献指南
• 安全政策
• 客户端配置指南
• 工具目录
• 项目概览

许可证

MIT。请参阅 LICENSE。

免责声明

本项目与 SAP SE 无关，未获其认可或赞助。文中提及的 SAP、SAP GUI 和其他 SAP 产品均为 SAP SE 的商标。

在 SAP 系统中使用本软件时，应遵守 SAP 许可协议和贵组织的安全政策。