SAP MCP 接入与部署

> 版本: 1.0.0 ｜ 更新: 2026-08-02 ｜ 适用范围: Windows + SAP GUI 7.x+/8.0、S/4HANA 与 ECC（NetWeaver 7.40+）

在 SAP 系统（S/4HANA/ECC）上部署 AI 接入能力：通过 aibap.mcp（ADT REST API） 编辑 ABAP 源码，或通过 mcp-sap-gui（SAP GUI Scripting COM 自动化） 执行事务查数据。

支持范围

版本历史

适用场景

• 用户要求"连接 SAP 系统让我编辑 SE38 代码"、"帮我查 SAP 数据"
• 部署 aibap.mcp 或 mcp-sap-gui 到 WorkBuddy/Claude/Cursor 等 MCP 客户端
• 排查 ADT 403/401 错误、SICF 激活、SAML SSO、Web Dispatcher 拦截
• SAP GUI Scripting 启用与 COM 接管

关键架构决策（先读这里）

部署步骤

第一步：收集环境信息（开始前先问清楚）

部署前必须先确认以下信息，缺失会导致反复调试：

1. 目标系统角色：开发 / 质量 / 生产？（决定用 ADT 还是 GUI 方案）
2. SAP 版本：S/4HANA 还是 ECC？（ADT 需 NetWeaver 7.40+）
3. HTTP/HTTPS 地址：不是 GUI 的 32xx 端口，是 ADT 的 HTTP(S) 地址（通常 https://<host>:44300 或 :8000）
4. 客户端号、开发账号、密码
5. 是否走 SAML SSO（浏览器访问是否跳转到 IAM 登录页）

第二步：探测 ADT 服务（关键前置）

# 1. 探测端口（HTTP 8000 常返回 307 重定向 → 跟随 location 得到真实 HTTPS 端口）
curl -sk -D - "http://<host>:8000/sap/bc/adt" | grep -i location

# 2. 验证 ADT 服务状态（403=未激活 / 401=已激活待认证 / 200=完全可用）
curl -sk -u "USER:PASS" -o /dev/null -w "%{http_code}\n" \
  "https://<host>:44300/sap/bc/adt/discovery?sap-client=<CLIENT>"

403 vs 401 判断：
- 403 Service nicht erreichbar（德语错误页）→ SICF 未激活，需要用户在 SICF 激活 /sap/bc/adt
- 401 → 服务已激活，查凭据/客户端号
- 200 → 完全可用

SAML SSO 系统识别：访问返回 302 跳转到 https://iam.<domain>/iam/auth/saml2/login → 该系统 ADT 和 OAuth2 端点都会被拦截，只能走 GUI 自动化方案。

第三步：aibap.mcp（ADT API，用于源码编辑）

1. 下载二进制：GitHub Hochfrequenz/aibap.mcp releases → aibap.mcp-<ver>-windows-amd64.zip，解压到 ~/.workbuddy/tools/aibap/
2. 创建凭据 ~/.config/sap-mcp/systems.json：
   json { "default_system": "dev", "systems": { "dev": { "host": "https://<host>:44300", "user": "<SAP_USER>", "password": "<SAP_PASSWORD>", "client": "<CLIENT>", "tls_skip_verify": true } } }
   > ⚠️ 不要包含无 user/password 的 OAuth2 系统——启动时会报 system "X" requires OAuth2 login — no stored token found 导致整个服务器启动失败。不需要的 SSO 系统就从配置移除。
3. 注册 MCP ~/.workbuddy/mcp.json：
   json "aibap-mcp": { "command": "C:\\Users\\<user>\\.workbuddy\\tools\\aibap\\aibap.mcp-<ver>.exe", "args": ["--tools=source,objects,locking,testing,version,messages,transport,system"], "env": { "SAP_CONFIG_FILE": "C:\\Users\\<user>\\.config\\sap-mcp\\systems.json" } }
4. 验证：MCP stdio 协议发 tools/call search_objects（query Z*, object_type PROG）→ 能搜到 Z 程序即成功

第四步：mcp-sap-gui（GUI 自动化，用于生产查数据）

1. 确认 ~/.workbuddy/mcp.json 已有 mcp-sap-gui 条目（uvx mcp-sap-gui[screenshots]）
2. 前置条件（三个缺一不可）：
   - 服务器端：RZ11 设置 sapgui/user_scripting = TRUE
   - 客户端：SAP GUI 按 Alt+F12 → 可访问性和脚本 → 勾选「启用脚本编写」
   - 必须有一个已登录的 SAP GUI 会话
3. 关键坑（最常见的故障）：mcp-sap-gui 进程必须在 SAP 会话登录之后启动！
   - 症状：sap_list_connections 报 RPC 服务器不可用 (-2147023174)
   - 修复：taskkill /F /PID <pid> 杀掉 mcp-sap-gui.exe，MCP 客户端会自动拉起新进程
4. 验证：sap_list_connections → sap_connect_existing → sap_get_session_info

第五步：ADT 403 排查速查

SICF 激活指引（给用户）：

SAP GUI → 事务 SICF → default_host → sap → bc → adt → 右键「激活服务」
（激活后无认证访问应从 403 变 401）

第六步：直接 COM 调用（绕过 mcp-sap-gui 的调试手段）

import win32com.client
app = win32com.client.GetObject('SAPGUI').GetScriptingEngine
for i in range(app.Connections.Count):
    c = app.Connections[i]
    for j in range(c.Sessions.Count):
        s = c.Sessions[j]
        print(s.Info.SystemName, s.Info.Client, s.Info.User, s.Info.Transaction)

注意：mcp-sap-gui 包内部用 app.Children（不是 Connections），两者等价。若直接 Python 调用成功但 MCP 报错，先重启 mcp-sap-gui 进程。

参考文件

• references/environment-example.md — 示例环境配置（含真实环境样例与坑位，可作模板参考）

常见错误速查

• RPC 服务器不可用 → mcp-sap-gui 需重启（SAP 会话登录后再启）
• system "X" requires OAuth2 login — no stored token → systems.json 里该系统的 user/password 被省略（OAuth2 模式）导致启动失败；不需要的 SSO 系统就从配置移除
• ADT 403 德语页 → SICF 激活
• GetObject('SAPGUI') 失败 → 确认 SAP GUI 已登录、脚本已启用
• 新版 SAP GUI 会话承载在 saplogon.exe 进程内，tasklist 看不到 sapgui.exe 是正常的，不影响 COM