sap-s4-mcp
# sap-s4-mcp
An MCP server that lets Claude (or any MCP client) read SAP S/4HANA data, and
propose changes that a person has to approve before anything is written.
I built it because the hard part of putting an LLM in front of an ERP is not
the query. It is making sure the model can't change financial data on its own,
and that you can show an auditor exactly what it looked at.
## What it does
| Tool | SAP API | Notes |
|---|---|---|
| `search_business_partners` | `API_BUSINESS_PARTNER` | Find customers and suppliers by name |
| `get_business_partner` | `API_BUSINESS_PARTNER` | One partner, with addresses |
| `list_sales_orders` | `API_SALES_ORDER_SRV` | Filter by customer and date, newest first |
| `get_sales_order` | `API_SALES_ORDER_SRV` | One order with its line items |
| `list_supplier_invoices` | `API_SUPPLIERINVOICE_PROCESS_SRV` | Filter by supplier and posting date |
| `propose_delivery_block` | `API_SALES_ORDER_SRV` | **Proposes** a change; nothing is written yet |
| `list_proposals` | local | Shows proposals and their status |
Example prompts once it's connected to Claude:
- "Which sales orders did customer 17100001 place since January? Total them by currency."
- "Show me supplier invoices posted this month and flag anything over 50,000."
- "Order 4711 looks like a credit risk. Propose a delivery block."
## How writes work
```
Claude ──propose_delivery_block──▶ approval queue (SQLite) ──▶ nothing sent to SAP
│
person runs: sap-s4-mcp approve <id>
▼
CSRF token ─▶ PATCH to SAP ─▶ audit log
```
- The model can only create a proposal. There is no tool that approves one.
- A person approves from the command line, sees the full change first, and has to type `y`.
- Writes are off unless `SAP_MCP_ALLOW_WRITES=true`, and they're always refused against the public sandbox.
- Every tool call, refusal, approval and failure goes into `~/.sap-s4-mcp/audit.jsonl`.
## Quick start
```bash
pip install -e ".[dev]"
export SAP_API_KEY=... # free key: https://api.sap.com → log in → "Show API Key"
python scripts/smoke_test.py # calls each read tool once against the sandbox
```
Add it to Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"sap": {
"command": "sap-s4-mcp",
"args": ["serve"],
"env": { "SAP_API_KEY": "your-key" }
}
}
}
```
To use your own tenant instead of the sandbox, set `SAP_BASE_URL`, `SAP_USER` and
`SAP_PASSWORD`. See `.env.example` for every setting.
Approving proposals:
```bash
sap-s4-mcp pending # what's waiting
sap-s4-mcp approve 3f9a1c2e # shows the change, asks y/N, then sends it
sap-s4-mcp reject 3f9a1c2e
sap-s4-mcp audit -n 50 # last 50 audit entries
```
## Design decisions
- **Filters are built, not passed through.** Tools take typed arguments (customer id,
date) and build the OData `$filter` themselves, with quotes escaped. Letting the model
write raw `$filter` strings is more flexible, but it's also how you get filter injection
and queries that pull a whole table.
- **Row cap.** `$top` is capped at `SAP_MCP_MAX_ROWS` (200 by default) whatever the model asks for.
- **Results are cleaned.** OData metadata and unexpanded navigation links are dropped, and
SAP's `/Date(ms)/` values become `YYYY-MM-DD`, so the model spends tokens on data.
- **Errors go back to the model as text** (with SAP's own message) instead of crashing the
call, so it can correct a bad date or id and try again.
- **One write, done properly** rather than many. A delivery block is a real, reversible
action that shows the whole approval path, including SAP's CSRF handshake.
## Tests
```bash
pytest
```
The tests use recorded SAP-style responses (via `respx`), so they run offline. They cover
filter escaping, date handling, the CSRF handshake, and the rule that a proposal sends
nothing to SAP until a person approves it.
## What I'd add next
- MCP elicitation so the approval can happen in the client UI, not only the CLI
- Purchase orders and goods receipts, for a three-way-match check
- OAuth for BTP-hosted tenants
## License
MIT
TDQS
Scored across 7 tools
Each tool has a distinct resource and action: business-partner search vs. lookup, sales-order get vs. list, supplier-invoice listing, and proposal workflow tools. There is little risk of an agent confusing the boundaries between these operations.
All tools follow a consistent snake_case verb_noun pattern, e.g. search_business_partners, get_sales_order, list_sales_orders, propose_delivery_block. The naming is predictable and readable throughout.
Seven tools is a well-scoped set for a focused SAP S/4 read-plus-proposal interface, and each tool has a clear role. The count is comfortably within a reasonable range and does not feel padded.
The surface covers business-partner lookup, sales-order retrieval, supplier-invoice listing, and one write proposal workflow, but notable gaps remain. There is no direct supplier-invoice detail getter, no business-partner list beyond search, and no broader sales-order create/update lifecycle coverage.