Skip to main content
Glama
sap-odata-mcp

sap-odata-mcp

by asherwalden

sap-odata-mcp

Ask your AI assistant about SAP data in plain English. An MCP server that lets Claude (or any MCP client) discover, understand, and query SAP S/4HANA OData services.

"Show me the 5 largest sales orders from last quarter and who the sold-to parties are."

demo


Why this exists

SAP data sits behind OData services with names like API_SALES_ORDER_SRV, entity sets like A_SalesOrder, and fields like SoldToParty. Answering a simple business question usually means knowing the service, reading its $metadata, and writing a $filter.

This server gives an AI agent three tools so it can do that loop itself:

Tool

What it does

sap_list_services

Shows the curated catalog of services, so the model knows where to look

sap_describe_entity_set

Reads $metadata and returns fields, types, labels, keys, and navigation properties

sap_query

Runs a read-only OData V2 query ($filter, $select, $expand, $orderby, paging)

Related MCP server: SAP S/4HANA MCP Server

Architecture

flowchart LR
    U[You] -->|plain English| C[Claude / MCP client]
    C <-->|JSON-RPC over stdio| S[sap-odata-mcp]
    subgraph S[sap-odata-mcp]
      T[tools/index.ts] --> Q[odata/query.ts<br/>build $filter, $select…]
      T --> M[odata/metadata.ts<br/>summarize EDMX]
      T --> CL[odata/client.ts<br/>fetch + APIKey + errors]
      CL --> N[odata/normalize.ts<br/>strip __metadata, fix /Date/]
    end
    CL <-->|HTTPS OData V2| SAP[(SAP Business Accelerator Hub<br/>S/4HANA Cloud sandbox)]

Design choices:

  • Read-only by design. Every tool is annotated readOnlyHint, and there are no create, update, or delete operations.

  • Context-window aware. Row caps, $select nudges, and response normalization keep the payloads small.

  • Errors are returned to the model, not thrown, so the agent can read SAP's error (for example, a misspelled field) and retry.

  • Sandbox first. It runs against SAP's public sandbox with a free personal API key, so no customer system is ever involved.

Quick start

git clone https://github.com/<you>/sap-odata-mcp && cd sap-odata-mcp
npm install
cp .env.example .env        # add your SAP_API_KEY (see below)
npm test                    # see what's left to implement
npm run inspect             # poke at the tools in the MCP Inspector UI

Get an API key: sign in at api.sap.com, open any S/4HANA Cloud API (for example, Sales Order (A2X)), go to Try Out, and click Show API Key.

Use it from Claude Desktop

npm run build, then add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "sap-odata": {
      "command": "node",
      "args": ["/absolute/path/to/sap-odata-mcp/dist/index.js"],
      "env": { "SAP_API_KEY": "your-key" }
    }
  }
}

Use it from Claude Code

claude mcp add sap-odata -e SAP_API_KEY=your-key -- node /absolute/path/to/sap-odata-mcp/dist/index.js

Project layout

src/
  index.ts            entry point: stdio transport
  config.ts           env validation with zod
  catalog.ts          curated services + descriptions (prompt engineering for tools)
  tools/index.ts      MCP tool definitions
  odata/
    client.ts         HTTP, auth header, SAP error parsing
    query.ts          ✍️ hand-written: OData query string builder
    normalize.ts      ✍️ hand-written: response cleanup
    metadata.ts       EDMX → compact schema summary
test/                 vitest specs (they define "done")
docs/ROADMAP.md       milestones + what each one teaches

What I learned

  • OData V2 URI conventions and why %2C vs , matters to SAP Gateway

  • …

  • …

Disclaimer

This is a personal learning project. It is not affiliated with or endorsed by SAP or my employer. It uses only SAP's public sandbox and mock data.

License

MIT

Available Tools

3 tools
sap_describe_entity_setDescribe an SAP entity setA
Read-only

Return the fields (name, type, label), keys and navigation properties of an entity set, from the service $metadata. Call this before building a $filter or $select so you use real field names.

Inputs: service (required), entitySet (required).

sap_list_servicesList SAP OData servicesA
Read-only

List the SAP S/4HANA OData services this server can query, with descriptions and key entity sets. Call this first.

Inputs: no named parameters.

sap_queryQuery SAP dataA
Read-only

Read records from an SAP OData V2 entity set using OData query options. Filter syntax examples: "SalesOrderType eq 'OR'", "TotalNetAmount gt 1000", "substringof('Inc', BusinessPartnerName)". Dates: "CreationDate ge datetime'2024-01-01T00:00:00'".

Inputs: service (required), entitySet (required), top, skip, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct step in a clear workflow: discover services, inspect an entity set's schema, then query records. Descriptions even state ordering guidance ('call this first', 'call this before building a $filter'), leaving no realistic chance of misselection.

    Naming Consistency5/5

    All three tools use a uniform sap_ prefix followed by a snake_case verb_noun form (list_services, describe_entity_set, query). The pattern is predictable and self-documenting.

    Tool Count4/5

    Three tools is on the thin edge but each has a clear, non-redundant role for a read-only OData gateway. It is well-scoped rather than padded, though the surface is minimal enough that some agents may want more entry points.

    Completeness3/5

    Discovery, schema introspection and querying are covered, but the surface is read-only: no create/update/delete, no function imports or actions, no count or paging helpers. These gaps are defensible for a query-focused server but will block write workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to integrate with SAP systems via OData REST APIs for querying entity sets, performing CRUD operations, and executing function imports. It features automatic service discovery, CSRF token management, and smart connection handling without requiring the SAP RFC SDK.
      11
      13
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables interaction with SAP S/4HANA systems via OData, allowing service discovery, metadata exploration, field value retrieval, and CRUD operations through natural language.
      4
      5
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude, ChatGPT, Copilot and Cursor to explore and query SAP S/4HANA's HANA database using SAP's data dictionary, organization structure, CDS views, and read-only SQL, with tools for finding tables, fields, joins, code values, and running SELECT queries. All access is read-only, with encrypted credentials and audited calls.
      2
      AGPL 3.0