Sap Mcp Server

SAP MCP - SAP Gateway Integration via Model Context Protocol

Complete MCP server for SAP Gateway integration, providing modular tools for SAP OData operations with AI agents.

[](https://www.python.org/downloads/) [](LICENSE) []() []() []()

---

📑 Table of Contents

• [🎯 Project Overview](#-project-overview)
• [⚡ Quick Start](#-quick-start)
• [📐 Architecture](#-architecture)
• [System Overview](#system-overview)
• [Component Details](#component-details)
• [Data Flow](#data-flow-order-query-example)
• [Tool Execution Flow](#tool-execution-flow)
• [Security Architecture](#security-architecture)
• [📦 Repository Structure](#-repository-structure)
• [✨ Features](#-features)
• [🎓 SAP SFLIGHT Demo Scenario](#-sap-sflight-demo-scenario)
• [Scenario Overview](#scenario-overview)
• [OData Service Creation Guide](#odata-service-creation-guide)
• [🚀 Getting Started](#-getting-started)
• [Prerequisites](#prerequisites-for-mcp-server)
• [Installation](#1-installation)
• [Configuration](#2-configuration)
• [Run Server](#3-run-server)
• [🤖 Integration with Gemini CLI](#-integration-with-gemini-cli)
• [Prerequisites](#prerequisites)
• [Install Gemini CLI](#1-install-gemini-cli)
• [Authenticate Gemini CLI](#2-authenticate-gemini-cli)
• [Register SAP MCP Server](#3-register-sap-mcp-server)
• [Start Using](#4-start-using-sap-mcp-with-gemini-cli)
• [Advanced Configuration](#advanced-configuration)
• [Troubleshooting](#troubleshooting)
• [Available Tools](#available-sap-tools-in-gemini-cli)
• [Example Workflows](#example-workflows)
• [🔧 Available Tools](#-available-tools)
• [SAP Authenticate](#1-sap-authenticate)
• [SAP Query](#2-sap-query)
• [SAP Get Entity](#3-sap-get-entity)
• [SAP List Services](#4-sap-list-services)
• [Adding a New Tool](#5-adding-a-new-tool)
• [📚 Usage Examples](#-usage-examples)
• [🔒 Security](#-security)
• [📖 Documentation](#-documentation)
• [📝 License](#-license)
• [🙏 Acknowledgments](#-acknowledgments)

---

🎯 Project Overview

Production-ready MCP (Model Context Protocol) server that enables AI agents and applications to interact with SAP Gateway systems through a clean, modular architecture. Built for reliability, security, and developer experience.

Current Status: ✅ Production Ready (All 5 phases completed)

Key Highlights

• 🔐 Secure SAP Integration: Enterprise-grade authentication and SSL/TLS support
• 🛠️ 4 Modular Tools: Authentication, query, entity retrieval, service discovery
• 🚀 Stdio Transport: Production-ready MCP server
• 📊 Structured Logging: JSON and console formats with performance metrics
• ✅ Validated Inputs: Comprehensive OData and security validation
• 🧪 Well-Tested: 56% coverage, 44/45 tests passing (98% success rate)

---

---

⚡ Quick Start

Get up and running with SAP MCP in 5 minutes:

# 1. Clone and navigate to project
git clone 
cd sap-mcp

# 2. Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
cd packages/server
pip install -e .

# 3. Configure SAP connection
cd ../..
cp .env.server.example .env.server
# Edit .env.server with your SAP credentials

# 4. Configure services
cp packages/server/config/services.yaml.example packages/server/config/services.yaml
# Edit services.yaml with your SAP services

# 5. Run the server
sap-mcp-server-stdio

Next Steps:

• 📖 See [Getting Started](#-getting-started) for detailed installation instructions
• 🤖 Check [Integration with Gemini CLI](#-integration-with-gemini-cli) to connect with AI agents
• 🔧 Explore [Available Tools](#-available-tools) for API documentation

📐 Architecture

System Overview

📊 Click to view System Overview Diagram

graph TB
    subgraph clients["🎯 Client Applications"]
        direction TB
        A1["AI AgentLLM/GenAI Integration"]
        A2["Python ClientSDK & Libraries"]
        A3["Order ChatbotExample Application"]
    end

    subgraph transport["🚀 MCP Server Layer"]
        direction TB
        B1["Stdio Transportstdin/stdout Stream"]
    end

    subgraph registry["🛠️ Tool Registry"]
        direction LR
        C1["sap_authenticateAuthentication"]
        C2["sap_queryOData Queries"]
        C3["sap_get_entityEntity Retrieval"]
        C4["sap_list_servicesService Discovery"]
    end

    subgraph core["⚡ Core Layer"]
        direction LR
        D1["SAP ClientOData Handler"]
        D2["Auth ManagerCredentials"]
        D3["Config LoaderYAML/ENV"]
    end

    subgraph utils["🔧 Utilities"]
        direction LR
        E1["ValidatorsInput/Security"]
        E2["LoggerStructured Logs"]
        E3["Error HandlerProduction Grade"]
    end

    subgraph sap["🏢 SAP Gateway"]
        direction TB
        F1["OData Servicesv2/v4 Protocol"]
        F2["Business DataOrders/Sales/Inventory"]
    end

    A1 & A2 & A3 -->|Active Connection| B1
    B1 -->|Tool Dispatch| C1 & C2 & C3 & C4
    C1 & C2 & C3 & C4 -->|Core Services| D1
    C1 -->|Auth Flow| D2
    C2 & C3 & C4 -->|Config Access| D3
    D1 & D2 & D3 -->|Validation & Logging| E1 & E2 & E3
    D1 -->|OData Protocol| F1
    F1 -->|Data Access| F2

    classDef clientNode fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,padding:20px
    classDef transportNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:20px
    classDef futureNode fill:#E8E8E8,stroke:#999999,stroke-width:2px,stroke-dasharray:5 5
    classDef toolNode fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px,padding:20px
    classDef coreNode fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,padding:20px
    classDef utilNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:20px
    classDef sapNode fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px,padding:20px

    class A1,A2,A3 clientNode
    class B1 transportNode
    class C1,C2,C3,C4 toolNode
    class D1,D2,D3 coreNode
    class E1,E2,E3 utilNode
    class F1,F2 sapNode

Component Details

🔧 Click to view Component Details Diagram

graph TB
    subgraph pkg["📦 packages/server/src/sap_mcp_server"]
        direction TB

        subgraph trans["🚀 transports/"]
            direction LR
            T1["stdio.pyCLI Entry Point"]
        end

        subgraph tools["🛠️ tools/"]
            direction TB
            TO5["base.pyTool Base Class"]

            subgraph toolImpl["Tool Implementations"]
                direction LR
                TO1["auth_tool.pyAuthentication"]
                TO2["query_tool.pyOData Query"]
                TO3["entity_tool.pySingle Entity"]
                TO4["service_tool.pyService List"]
            end
        end

        subgraph core["⚡ core/"]
            direction LR
            C1["sap_client.pyOData Client"]
            C2["auth.pyAuth Manager"]
            C3["exceptions.pyCustom Errors"]
        end

        subgraph config["⚙️ config/"]
            direction LR
            CF1["settings.pyEnv Config"]
            CF2["loader.pyYAML Loader"]
            CF3["schemas.pyPydantic Models"]
        end

        subgraph utils["🔧 utils/"]
            direction LR
            U1["logger.pyStructured Logs"]
            U2["validators.pyInput Validation"]
        end

        subgraph protocol["📡 protocol/"]
            P1["schemas.pyMCP Request/Response"]
        end
    end

    T1 -->|Dispatches to| TO1 & TO2 & TO3 & TO4
    TO1 & TO2 & TO3 & TO4 -.->|Extends| TO5
    TO5 -->|Uses| C1 & C2
    C1 -->|Loads| CF1 & CF2
    C2 -->|Reads| CF1
    C1 & C2 -->|Validates & Logs| U1 & U2
    TO5 -.->|Implements| P1
    C3 -.->|Error Types| C1 & C2

    classDef transportNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:18px
    classDef futureNode fill:#E8E8E8,stroke:#999999,stroke-width:2px,stroke-dasharray:5 5
    classDef toolNode fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px,padding:18px
    classDef baseNode fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,padding:18px
    classDef coreNode fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,padding:18px
    classDef configNode fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,padding:18px
    classDef utilNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:18px
    classDef protocolNode fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px,padding:18px

    class T1 transportNode
    class TO1,TO2,TO3,TO4 toolNode
    class TO5 baseNode
    class C1,C2,C3 coreNode
    class CF1,CF2,CF3 configNode
    class U1,U2 utilNode
    class P1 protocolNode

Data Flow: Order Query Example

🔄 Click to view Data Flow Diagram

sequenceDiagram
    autonumber
    box rgba(214, 234, 248, 0.3) Client Layer
        participant Client as 🤖AI Agent/Client
    end
    box rgba(213, 245, 227, 0.3) Transport Layer
        participant Transport as 📡Stdio Transport
        participant Registry as 📋Tool Registry
    end
    box rgba(252, 243, 207, 0.3) Tool Layer
        participant AuthTool as 🔐Auth Tool
        participant QueryTool as 🔍Query Tool
    end
    box rgba(250, 219, 216, 0.3) Core Layer
        participant SAPClient as 🔧SAP Client
    end
    box rgba(213, 245, 227, 0.3) Support Layer
        participant Validator as ✅Validator
        participant Logger as 📊Logger
    end
    box rgba(235, 222, 240, 0.3) External
        participant SAP as 🏢SAP Gateway
    end

    rect rgba(214, 234, 248, 0.15)
        Note over Client,Registry: ⚡ Phase 1: Session Initialization
        Client->>+Transport: Connect via stdio stream
        Transport->>+Registry: Initialize tool registry
        Registry-->>-Transport: ✅ 4 tools registered
        Transport-->>-Client: Connection established
    end

    rect rgba(213, 245, 227, 0.15)
        Note over Client,SAP: 🔐 Phase 2: Authentication
        Client->>+Transport: call_tool(sap_authenticate, {})
        Transport->>+Registry: Get tool: sap_authenticate
        Registry->>+AuthTool: Execute authentication
        AuthTool->>+Validator: Validate credentials
        Validator-->>-AuthTool: ✅ Credentials valid
        AuthTool->>+Logger: Log authentication attempt
        Logger-->>-AuthTool: Logged
        AuthTool->>+SAPClient: Authenticate with SAP
        SAPClient->>+SAP: POST /sap/opu/odata/auth
        SAP-->>-SAPClient: 200 OK + Session token
        SAPClient-->>-AuthTool: ✅ Authenticated successfully
        AuthTool-->>-Registry: Success response
        Registry-->>-Transport: Auth token + session ID
        Transport-->>-Client: ✅ Authentication complete
    end

    rect rgba(252, 243, 207, 0.15)
        Note over Client,SAP: 🔍 Phase 3: Query Execution
        Client->>+Transport: call_tool(sap_query, {filter: "OrderID eq '91000043'"})
        Transport->>+Registry: Get tool: sap_query
        Registry->>+QueryTool: Execute with parameters
        QueryTool->>+Validator: Validate OData filter syntax
        Validator-->>-QueryTool: ✅ Filter is safe
        QueryTool->>+Logger: Log query start
        Logger-->>-QueryTool: Logged
        QueryTool->>+SAPClient: Execute OData query
        SAPClient->>+SAP: GET /OrderSet?$filter=OrderID eq '91000043'
        SAP-->>-SAPClient: 200 OK + Order data (JSON)
        SAPClient->>SAPClient: Parse & transform response
        SAPClient-->>-QueryTool: ✅ Parsed order data
        QueryTool->>+Logger: Log query success + metrics
        Logger-->>-QueryTool: Logged
        QueryTool-->>-Registry: Order details
        Registry-->>-Transport: Formatted response
        Transport-->>-Client: ✅ Query complete
    end

    rect rgba(213, 245, 227, 0.15)
        Note over Logger: 📊 Phase 4: Performance Tracking
        Logger->>Logger: Calculate execution metrics
        Logger->>Logger: Write structured JSON log
        Logger->>Logger: Update performance counters
    end

Tool Execution Flow

⚡ Click to view Tool Execution Flow Diagram

flowchart TD
    Start([🚀 Client RequestTool invocation])

    Start --> Validate{🔍 Validate InputSchema checkSecurity scan}

    Validate -->|❌ Invalid| Error1[🚫 Validation ErrorReturn error details]
    Validate -->|✅ Valid| Auth{🔐 Authenticated?Session check}

    Auth -->|No| DoAuth[🔑 Execute AuthCredential validationSAP handshake]
    DoAuth --> AuthCheck{✅ Auth Success?Token received}

    AuthCheck -->|❌ Failed| Error2[🚫 Auth ErrorInvalid credentials]
    AuthCheck -->|✅ Success| Execute

    Auth -->|Yes| Execute[⚡ Execute ToolBusiness logicParameter processing]

    Execute --> SAPCall[🌐 SAP OData CallHTTP requestSSL/TLS encrypted]

    SAPCall --> SAPCheck{📡 SAP ResponseStatus check}

    SAPCheck -->|❌ Error| Error3[🚫 SAP ErrorService unavailableor data error]
    SAPCheck -->|✅ 200 OK| Parse[📊 Parse ResponseXML/JSON parsingData extraction]

    Parse --> Transform[🔄 Transform DataMCP formatSchema mapping]

    Transform --> Log[📝 Log MetricsPerformance dataAudit trail]

    Log --> Success([✅ Success ResponseReturn to client])

    Error1 & Error2 & Error3 --> LogError[📝 Log ErrorError contextStack trace]

    LogError --> End([❌ Error ResponseReturn to client])

    classDef startNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:18px
    classDef decisionNode fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px,padding:18px
    classDef authNode fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px,padding:18px
    classDef processNode fill:#D6EAF8,stroke:#3498DB,stroke-width:2px,padding:18px
    classDef sapNode fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,padding:18px
    classDef errorNode fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,padding:18px
    classDef logNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:18px
    classDef successNode fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px,padding:18px
    classDef endNode fill:#FADBD8,stroke:#E74C3C,stroke-width:2px,padding:18px

    class Start startNode
    class Validate,SAPCheck,AuthCheck decisionNode
    class DoAuth authNode
    class Execute,Parse,Transform processNode
    class SAPCall sapNode
    class Error1,Error2,Error3 errorNode
    class Log,LogError logNode
    class Success successNode
    class End endNode

Security Architecture

🔒 Click to view Security Architecture Diagram

%%{init: {'theme':'base', 'themeVariables': {'fontSize':'14px', 'fontFamily':'arial'}}}%%
graph TB
    subgraph security["🛡️ Defense in Depth Security Architecture"]
        direction TB

        subgraph layer1["Layer 1: Input Validation - Entry Point Security"]
            direction LR
            L1A["🔍 OData FilterSQL injectionpreventionSyntax validation"]
            L1B["🔑 Entity KeyFormatvalidationType checking"]
            L1C["🧹 SanitizationXSSpreventionInput cleaning"]
        end

        subgraph layer2["Layer 2: Authentication - Identity Verification"]
            direction LR
            L2A["✅ CredentialsUservalidationPassword checks"]
            L2B["🎫 SessionsSessionlifecycleTimeout handling"]
            L2C["🔐 TokensJWT/BearertokensToken rotation"]
        end

        subgraph layer3["Layer 3: Authorization - Access Control"]
            direction LR
            L3A["🚦 Service AccessService-levelRBACPermission matrix"]
            L3B["📋 Entity PermissionsData-levelaccessField filtering"]
        end

        subgraph layer4["Layer 4: Transport Security - Encryption Layer"]
            direction LR
            L4A["🔒 SSL/TLSTLS 1.2+ onlyPerfect forwardsecrecy"]
            L4B["📜 CertificatesChainvalidationRevocation check"]
        end

        subgraph layer5["Layer 5: Audit & Monitoring - Observability"]
            direction LR
            L5A["📊 Structured LogsJSON loggingPII exclusion"]
            L5B["⚡ PerformanceMetricstrackingSLA monitoring"]
            L5C["🚨 Error TrackingExceptionloggingAlert triggers"]
        end
    end

    L1A & L1B & L1C -->|Validated Input| L2A
    L2A -->|Identity Verified| L2B
    L2B -->|Session Active| L2C
    L2C -->|Authenticated| L3A & L3B
    L3A & L3B -->|Authorized| L4A & L4B
    L4A & L4B -->|Encry

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [midasol](https://github.com/midasol)
- **Source:** [midasol/sap-mcp-server](https://github.com/midasol/sap-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.