bw-modeling-mcp

A Model Context Protocol (MCP) server that enables AI assistants like Claude to work directly inside SAP BW/4HANA or SAP BW 7.5 on HANA systems — reading, creating and modifying BW modeling objects via the same internal SAP APIs that Eclipse BWMT and the BW/4HANA Cockpit use: the BW Modeling REST API (/sap/bw/modeling/) for objects, queries and live data, the ADT API (/sap/bc/adt/) for the ABAP and AMDP routines BW generates, the BW/4HANA manage API for the request monitor and runtime, and the Push API (/sap/bw4/) for data loads.

This is not a simulation. Every tool call connects to a live BW system — write operations produce real changes.

☁️ Running on SAP BTP Cloud Foundry

Besides stdio, the server can run as an HTTP service on SAP BTP Cloud Foundry with XSUAA OAuth in front and a BTP destination behind — either a shared technical user (BasicAuthentication) or principal propagation, where each caller reaches BW as themselves and BW applies their own authorizations.

Three role collections decide what a user is offered: BW MCP Reader (everything that only reads), BW MCP Analyst (a small reporting client — run queries and understand what they return) and BW MCP Developer (everything, including changes). stdio is unchanged — npm start behaves exactly as before. Setup: docs/CENTRAL-HOSTING-SETUP.md (step-by-step) and docs/CLOUD-FOUNDRY.md (reference).

What central hosting changes

A new tool stays unavailable to read-only callers until it is explicitly classified as a read, so the surface never widens by accident; write implies read, never the reverse. The three role collections are a starting point and can be split further in xs-security.json. Principal propagation additionally needs a certificate rule and ICM trust on the BW side.

Related MCP server: abap-adt-mcp

System Compatibility

📖 Featured Blog Posts

A two-part blog series about this project (both available in German and English):

1. Agentic AI meets SAP BW — the full story behind this project: why I built it, what's inside, what happens when Claude walks through a complete BW data lineage on its own. https://www.nextlytics.com/blog/agentic-ai-meets-sap-bw

2. Agentic AI in practice: MCP server for SAP BW/4HANA — how the server is operated company-wide on SAP BTP Cloud Foundry with role-based access and per-user identity, plus two real customer projects. https://www.nextlytics.com/blog/agentic-ai-in-practice-mcp-server-for-sap-bw/4hana

🆕 What's New — v2.0.0 · 21 Tools Instead of 134

The largest release so far, in two directions at once: the model now works with a tool surface a third the size, and the write paths have been checked operation by operation against what BW actually accepts — so a change the server reports as saved also activates.

🎯 Focused tool surface, now the default

• 21 tools instead of 134. Each focused tool stands for a group of operations and selects one through its type or operation parameter: bw_read reads any object type, bw_write_adso creates and changes aDSOs, bw_activate checks, activates and unlocks. Nothing was removed — every operation is still there, with the same parameters and behaviour

• A third of the context. The tool definitions take about a third of the space they took before, which leaves the model more room for the actual work. In our tool-selection benchmark it picked the right operation as often on the focused surface as on the full one

• bw_describe on demand. The focused tools carry short parameter notes; bw_describe(tool, operation) returns the complete definition of one operation when the model needs it, and a wrong or missing operation is refused with the allowed values before anything reaches BW

• Roles and platform still apply per operation: a Reader sees only the reading operations, and a BW 7.5 system only what it can answer

Upgrading to 2.0

The one breaking change: clients now see the focused tool names.

• Allowlists and permission settings that name full tools (bw_get_adso, bw_update_transformation, …) need the focused names (bw_read, bw_write_transformation, …) — or set BW_TOOL_MODE=full to keep the full surface exactly as it was

• Scripts and automations that call the server directly with full tool names keep working without a change: a full tool name sent to the server is answered in either mode

• Skills and prompts that name full tools in their text are best moved to the focused names — an agent can only pick from the tools it is shown — or run with BW_TOOL_MODE=full

• Hosted on SAP BTP: role collections and scopes are unchanged

• The mapping from every full tool to its focused tool and operation is in Tool modes

On every release (BW/4HANA and BW 7.5)

✅ Check before you activate

• New bw_check (operation check of bw_activate) — runs the activation checks on the saved version of an object, as "Check" in the modeling tools does, without activating anything and without a lock. The answer says whether the object would activate and why not. It is a read operation, so read-only users can use it too

🧱 Writes that activate the first time

• aDSO — a type change now writes the type as a whole and drops what the new type cannot carry; removing a field removes its key, partition and index entries with it; an InfoObject brings its compounding parents along; key fields are checked before they are saved, and every one of these is reported in the answer

• CompositeProvider — update_join gives both sides of a join key the common target field BW requires, a compounded field brings its compounding parent, and mapping an input again no longer leaves duplicate fields behind

• InfoObject — attributes can be key figures, units and time characteristics, display attributes can be time-dependent, and a navigation attribute BW would refuse is refused before anything is written

🆕 New capabilities

• Open Hub Destinations can be created from an aDSO or CompositeProvider and changed — table and file destinations, write mode, key, fields and file properties (bw_create_open_hub, bw_update_open_hub)

• Partitions and data tiering of an aDSO — static range partitions or dynamic partitioning (manage_partitions), hot and warm storage per object or per partition

• Master data, text and hierarchy properties of a characteristic — text lengths, language- and time-dependent texts, hierarchies with version and time dependency

BW/4HANA

🔀 Transformations and DTPs

• The rule of a field can be changed from any type to any other — direct, time conversion, constant, formula, routine with several source fields, lookup — and a lookup binds every key field of the object it reads from

• bw_update_dtp takes the execution settings: package size and parallel extraction, request selection, error handling, SAP HANA execution and the batch manager. Each value is checked against what the server admits for that DTP, so an inadmissible setting is refused with the admissible ones instead of an HTTP 500 without a message

📤 Open Hub from a query

• A query can be released as an InfoProvider and used as the template and source of an Open Hub Destination, so the result of a query lands in a table or file through a DTP

Also in this release

• Query structures: where a hierarchy holds a text node and a characteristic value of the same name, node_type says which one a restriction means, and switch_hierarchy keeps the kind of each node (#52)

• Fixed: bw_update_infoobject reported a refused activation as success — the answer now carries the server's messages and says that the change is saved but not active; a characteristic with a compounded attribute can be changed again; bw_run_dtp says when a delta found nothing to load instead of reporting a started request; bw_get_request refuses a malformed request id instead of returning the whole process history; texts with & or quotes no longer break a save

Earlier releases — the "What's New" notes for v1.10.0 and older are archived in WHATS_NEW.md; the full structured history is in CHANGELOG.md.

What it can do

An overview by area. Every tool in detail — parameters, behaviour, and the sequences it belongs in — is in the Tools Reference (134 operations behind 21 focused tools).

Combining with an ADT MCP Server

bw-modeling-mcp works best alongside an ADT MCP server such as vibing-steampunk or ARC-1. The two do not overlap as much as it may look.

This server owns the BW object and, with it, the body of the ABAP that BW generated for that object: the class behind a transformation routine, the program behind a DTP filter routine. Write those through bw_set_transformation_routine, bw_set_transformation_expert_routine and bw_set_dtp_filter_routine rather than through ADT — they do not only replace the source, they save the transformation master back afterwards, which is what re-registers the code in the transportable metadata. A class-only edit survives until the next regeneration or transport and is then gone.

The ADT MCP server covers ABAP as a subject in its own right: your own reports, classes, function modules and DDIC tables, repository search and navigation, arbitrary table reads, debugging, ATC, unit tests, dumps and transports. Together they cover the full cycle from BW object to ABAP logic.

Requirements

• SAP BW/4HANA system with the internal SAP APIs enabled (SAP BW 7.5 works for modeling reads and most modelling writes once the enhancement in bw75/BW75-SUPPORT.md is in place)

• Node.js 22 or later

• An MCP-compatible AI client (Claude Desktop, Claude Code, etc.)

Installation

Two ways to run. Locally as a stdio server (one user, one machine — the steps below), or centrally hosted on SAP BTP Cloud Foundry behind XSUAA OAuth for a whole team → see docs/CENTRAL-HOSTING-SETUP.md. The installation and configuration below cover local stdio use. Upgrading from 1.x: see Upgrading to 2.0.

# Option 1: Install via npm (recommended)
npm install -g bw-modeling-mcp

# Option 2: Clone and build
git clone https://github.com/dnic-dev/bw-modeling-mcp.git
cd bw-modeling-mcp
npm install
npm run build

Configuration

For local (stdio) use, the server is configured via environment variables. For central BTP hosting, connection and credentials come from the BTP destination and service bindings instead — see docs/CENTRAL-HOSTING-SETUP.md.

Cookie authentication (BW Bridge / SAP BTP): For BW systems that sit behind a SAML or OAuth login (such as BW Bridge on the SAP BTP ABAP stack), Basic Auth is not available. Export the authenticated session cookies from your browser into a file and point BW_COOKIE_FILE at it. The login/session approach is analogous to vibing-steampunk and ARC-1. When the session expires, refresh the cookie file and restart the server.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bw-modeling-mcp": {
      "command": "node",
      "args": ["/path/to/bw-modeling-mcp/dist/stdio.js"],
      "env": {
        "BW_URL": "https://your-bw-host:50001",
        "BW_USER": "YOUR_USER",
        "BW_PASSWORD": "YOUR_PASSWORD",
        "BW_CLIENT": "001",
        "BW_LANGUAGE": "EN"
      }
    }
  }
}

Claude Code (VS Code extension)

Add .mcp.json to your project root:

{
  "mcpServers": {
    "bw-modeling-mcp": {
      "command": "node",
      "args": ["/path/to/bw-modeling-mcp/dist/stdio.js"],
      "env": {
        "BW_URL": "https://your-bw-host:50001",
        "BW_USER": "YOUR_USER",
        "BW_PASSWORD": "YOUR_PASSWORD",
        "BW_CLIENT": "001",
        "BW_LANGUAGE": "EN"
      }
    }
  }
}

How it works

The server talks to four SAP APIs, and only one of them needs a protocol worth describing.

The BW Modeling REST API (/sap/bw/modeling/) is a full-document API: there is no way to change one attribute of an object. Every write therefore runs the same six steps.

1. Lock — acquires an exclusive lock and returns a lockHandle

2. Read — fetches the current complete XML of the object

3. Modify — applies the change to that XML

4. PUT — sends the whole document back, never a fragment

5. Activate — promotes the inactive version to the active one

6. Unlock — releases the lock

Two consequences are worth knowing. Saving and activating are separate: a document the server accepts can still fail to activate, so a successful write proves less than it appears to. And because the whole document travels, a read that came from a stale session buffer will silently write old values back — the tools read fresh for exactly this reason.

The other three need none of it. The ADT API (/sap/bc/adt/) is used narrowly and always for an object BW generated itself: the body of a transformation routine (its generated class), the body of a DTP filter routine (its generated program), the DataPreview service behind bw_read_metadata_tables, plus transport checks and activation runs. Everything else ABAP — writing your own reports, classes or DDIC tables, searching the repository, reading arbitrary tables, debugging — is the job of an ABAP ADT MCP server alongside this one, see Combining with an ADT MCP Server. The BW/4HANA manage API (/sap/bc/http/sap/bw4/) answers the request monitor, the remodeling monitor and runtime operations. The Push API (/sap/bw4/v1/push/) takes a JSON record array straight into a write-interface aDSO.

Session cookies and CSRF tokens are handled for all four.

See ARCHITECTURE.md for the full technical architecture and the complete endpoint reference.

Contributing

Issues and feature requests are welcome — please use the Issue templates.

If you have access to a BW/4HANA system and want to help expand coverage, I am happy to hear from you. The best way to contribute is to try it out and report what works, what doesn't, and what's missing.

License

MIT