S/4HANA MCP Server

SAP S/4HANA(Cloud Public Edition 및 on-premise Private Edition)용 OData V2, OData V4, SOAP를 통해 38개의 도구를 제공하는 MCP 서버입니다: 비즈니스 파트너, 제품, 판매 가격, 창고, 구매 오더, 구매 정보 레코드, 공급업체 인보이스(전기 및 취소 포함), 서비스 입고 시트, 전표, 원가 센터, 재무 조직 구조.

쓰기 도구(create_*, cancel_supplier_invoice, check_invoice_posting_readiness) 및 get_finance_structure는 결과를 JSON으로 인라인 반환합니다. 다른 모든(읽기) 도구는 결과(컬렉션은 CSV, 단일 레코드는 Markdown)를 E2B 샌드박스에 쓰고 파일 경로를 반환하며, 잠재적으로 큰 SAP 결과 집합(수백 개의 비즈니스 파트너, 전체 전표 항목 세부 정보 등)을 호출 에이전트의 컨텍스트에 직접 인라인하지 않습니다. 이 서버는 MCP 클라이언트가 이미 소유한 E2B 샌드박스에만 연결하며, 절대 생성하지 않습니다. 클라이언트는 파일을 다시 읽기 위해 자체 E2B 통합(E2B SDK 또는 일치하는 코드 실행 액세스 권한이 있는 Claude 환경)이 필요합니다. E2B 샌드박스 설정을 참조하세요.

빠른 시작

git clone https://github.com/ilia-inovaflow/s4hana-mcp-server.git
cd s4hana-mcp-server
npm install
npm run build
cp .env.example .env   # fill in your E2B sandbox + SAP connection details
npm start               # stdio transport (Claude Desktop, MCP Inspector, etc.)

빌드 없이 로컬 개발: npm run dev.

Related MCP server: SAP OData MCP Server

E2B 샌드박스 설정

e2b.dev에서 무료 API 키를 등록한 다음, MCP 클라이언트가 파일을 읽을 수 있는 샌드박스를 시작(또는 재사용)하고 다음을 설정합니다:

E2B_API_KEY=<your E2B API key>
SANDBOX_ID=<an already-running sandbox ID>   # stdio only — HTTP takes this per-session

HTTP 전송에서는 SANDBOX_ID가 대신 sandbox-id 요청 헤더를 통해 세션별로 제공됩니다. 이는 하나의 실행 중인 서버 인스턴스가 각각 자체 샌드박스를 가진 여러 호출자를 처리할 때 유용합니다.

이는 아래의 SAP 자체 sandbox.api.sap.com 평가판 호스트와는 무관합니다. 이 README에서 "sandbox"는 두 가지 다른 의미를 가집니다.

자체 SAP 테넌트 없이 사용해 보기

SAP는 이 서버가 기본적으로 통신하는 무료 공개 읽기 전용 API 샌드박스를 sandbox.api.sap.com에 게시합니다. api.sap.com에서 무료 API 키를 등록한 후 다음을 설정합니다:

SAP_HOST=https://sandbox.api.sap.com
SAP_CLIENT_ID=<your sandbox API key>

사용자 이름, 비밀번호 또는 OAuth 설정이 필요 없습니다. 샌드박스는 단일 APIKey 헤더로 인증합니다. 비즈니스 파트너, 제품 및 가격 도구는 샌드박스 데모 데이터에서 즉시 작동합니다(읽기 도구 결과를 받으려면 위의 E2B 샌드박스가 여전히 필요합니다).

실제 SAP 테넌트 연결

SAP_HOST를 테넌트 URL로 설정하고 SAP_AUTH_MODE를 통해 세 가지 인증 모드 중 하나를 선택합니다:

SAP_CLIENT(SAP 클라이언트/멘던트 번호, 예: 100)는 설정하지 않으면 기본값 100입니다.

두 API 계열은 SAP 설계상 basic 또는 X.509 인증이 필요하며 OAuth를 거부합니다: 전표 전기(create_journal_entry, SOAP SAP_COM_0002) 및 회계 문서 세부 보기(get_journal_entry, search_journal_entries with document_level=true). 다른 모든 것은 세 가지 모드 중 어느 것이든 작동합니다.

전체 변수 목록은 .env.example을 참조하세요. 일부 온프레미스 SOAMANAGER 구성에 필요한 선택적 SAP_JE_SOAP_PATH 재정의도 포함됩니다.

전송

stdio(기본값, npm start / npm run dev) — 프로세스당 하나의 SAP 연결과 하나의 E2B 샌드박스, 전적으로 .env에서 구성됩니다. 이는 Claude Desktop 및 대부분의 로컬 MCP 클라이언트가 기대하는 방식입니다:

{
  "mcpServers": {
    "s4hana": {
      "command": "node",
      "args": ["/absolute/path/to/s4hana-mcp-server/dist/index.js"],
      "env": {
        "E2B_API_KEY": "...", "SANDBOX_ID": "...",
        "SAP_HOST": "...", "SAP_AUTH_MODE": "basic", "SAP_USERNAME": "...", "SAP_PASSWORD": "..."
      }
    }
  }
}

Streamable HTTP(npm run start:http / npm run dev:http) — 원격 또는 멀티 테넌트 배포용. 각 세션의 SAP 연결은 .env 기본값 또는 요청별 헤더(sap-host, sap-auth-mode, sap-username, sap-password, sap-token-url, sap-client-id, sap-client-secret, sap-client, sap-je-soap-path)로 구성되고, E2B 샌드박스는 sandbox-id 헤더(또는 대체로 SANDBOX_ID 환경 변수)로 구성됩니다. 이를 통해 하나의 실행 중인 서버가 다른 테넌트와 샌드박스에 대한 요청을 처리할 수 있습니다. E2B_API_KEY는 항상 서버 자체 환경에서 읽습니다. PORT(기본값 3000) 및 HOST(기본값 localhost)는 리스너를 구성합니다. MCP 엔드포인트는 POST /mcp이고, GET /health는 활성 상태 확인용입니다.

HTTP 전송을 네트워크에서 접근 가능한 곳에 배포하는 경우 자체 인증/네트워크 경계 뒤에 두십시오. 이 서버는 /mcp 엔드포인트에 대한 액세스를 자체적으로 차단하지 않으며, 다운스트림 SAP 연결에만 게이트를 둡니다.

도구

• search_business_partners — 고객, 공급업체, 개인, 조직 검색

• get_business_partner — 단일 비즈니스 파트너의 전체 세부 정보

• query_business_partner_odata — 모든 API_BUSINESS_PARTNER 엔티티 집합에 대한 일반 쿼리

• search_products — 자재, 완제품, 서비스, 원자재 검색

• get_product — 단일 제품의 전체 세부 정보

• query_product_odata — 모든 API_PRODUCT_SRV 엔티티 집합에 대한 일반 쿼리

• get_product_pricing — 자재에 대한 결합 가격 조회("X 비용은 얼마인가"로 시작)

• search_pricing_conditions — 유형/요율별 조건 레코드 탐색

• get_pricing_condition — 단일 조건 레코드의 전체 세부 정보

• query_pricing_odata — 모든 가격 엔티티 집합에 대한 일반 쿼리

• list_warehouses

• get_warehouse

• search_purchase_orders

• get_purchase_order

• query_purchase_order_odata — 항목/일정 라인 수준을 포함한 일반 쿼리

• get_purchase_order_confirmations — 공급업체 오더/배송/GR 확인, 대량 조회

• search_purchasing_info_records

• get_purchasing_info_record

• query_purchasing_info_record_odata

• search_supplier_invoices

• get_supplier_invoice

• query_supplier_invoice_odata

• create_supplier_invoice_po ⚠️ 쓰기 — PO 참조 3-way 매치 인보이스

• create_supplier_invoice_gl ⚠️ 쓰기 — PO 미참조 비용 인보이스, 직접 G/L 라인

• create_supplier_credit_memo ⚠️ 쓰기 — PO 참조 대변 메모

• cancel_supplier_invoice ⚠️ 쓰기 — 전기된 인보이스 또는 대변 메모 취소

• check_invoice_posting_readiness — 읽기 전용 사전 점검 가드

• search_service_entry_sheets

• get_service_entry_sheet

• query_service_entry_sheet_odata

• create_journal_entry ⚠️ 쓰기 — G/L 문서 전기(SOAP, basic/X.509 인증 전용)

• search_journal_entries — 분석(집계) 또는 회계 문서(라인 수준) 보기

• get_journal_entry — 번호로 단일 회계 문서 조회

• search_gl_accounts

• search_open_po_items — 공급업체의 아직 인보이스 가능한 PO 라인을 한 번에 조회

• search_cost_centers

• get_cost_center_hierarchy — 표준 원가 센터 계층 트리

• get_finance_structure — 회사 코드, 원장, 계정과목표, 세그먼트, 사업 영역

모든 쓰기 도구는 전기 전에 서버 측 가드 검사(존재 여부, 차단 플래그, 중복 감지, 잔액 검증)를 실행하고, 가드가 실패하면 SAP에 아무것도 보내지 않고 구조화된 이유 목록을 보고합니다. 결정적 SAP 거부(닫힌 전기 기간, 누락된 세금 관할 등)는 원시 오류 코드 대신 실행 가능한 메시지로 변환됩니다.

아키텍처

src/
├── server.ts       # McpServer factory — tool registration, schemas, annotations
├── client.ts        # SapClient — OData V2/V4 requests, CSRF-protected writes, SOAP posts
├── auth.ts           # Auth strategies: Basic, OAuth Client Credentials, OAuth Authorization Code
├── config.ts          # Connection config + SAP public sandbox detection
├── index.ts             # stdio entry point
├── http.ts               # Streamable HTTP entry point (Express, per-session auth)
└── tools/
    ├── shared.ts          # OData/CSV/error-parsing + E2B sandbox file I/O, shared by every tool
    └── *.ts                # one file per tool (schema + handler)

OData V2 엔드포인트에 대한 쓰기는 SAP의 CSRF 토큰 프로토콜을 따릅니다: GET에 X-CSRF-Token: Fetch로 토큰을 가져오고, POST에 세션 쿠키와 함께 다시 보내며, 403이면 한 번 재시도합니다. 전표 전기는 대신 원시 SOAP 봉투를 구성하여 보냅니다. 해당 API에는 OData 등가물이 없기 때문입니다.

개발

npm run dev        # stdio, hot reload via tsx
npm run dev:http    # HTTP, hot reload via tsx
npm run typecheck    # tsc --noEmit
npm run build          # compile to dist/

라이선스

MIT