shopware-mcp

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/brand/banner-dark.svg">
    <img src="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/brand/banner-light.svg" alt="shopware-mcp: the MCP server for Shopware 6" width="100%">
  </picture>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/shopware-mcp"><img src="https://img.shields.io/npm/v/shopware-mcp?color=cb3837&logo=npm&logoColor=white" alt="npm"></a>
  <a href="https://github.com/bnymnDev/shopware-mcp/actions/workflows/ci.yml"><img src="https://github.com/bnymnDev/shopware-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/bnymnDev/shopware-mcp/actions/workflows/e2e.yml"><img src="https://github.com/bnymnDev/shopware-mcp/actions/workflows/e2e.yml/badge.svg" alt="nightly e2e against a real Shopware"></a>
  <a href="https://registry.modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_registry-io.github.bnymnDev%2Fshopware--mcp-0b7bd6" alt="MCP registry"></a>
  <img src="https://img.shields.io/node/v/shopware-mcp?color=339933&logo=node.js&logoColor=white" alt="node">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
</p>

<p align="center">
  <a href="#introducing-shopware-mcp">Why</a> ·
  <a href="#see-it-work">Demo</a> ·
  <a href="#60-seconds">Install</a> ·
  <a href="#tools">Tools</a> ·
  <a href="#safety">Safety</a> ·
  <a href="#documentation">Docs</a> ·
  <a href="https://bnymndev.github.io/shopware-mcp/">Website</a> ·
  <a href="README.de.md">Deutsch</a>
</p>

---

## Introducing shopware-mcp

A Shopware 6 shop is about two hundred entities behind one Admin API. Ask an
assistant "is everything okay with the shop?" and the honest answer takes seven
searches with Criteria filters, three state machines by their technical names,
a couple of aggregations, and an OAuth token it must never repeat back to you.
Wire a model straight to that API and it gets all of it, including the right to
`PATCH` a price because a prompt said so.

The Model Context Protocol turned "give the model real tools" into a one-line
config change. It says nothing about what a good tool for a *shop* looks like:
which of the two hundred entities matter on a Tuesday morning, what "stuck
order" means, or that a stock correction should be shown before it is sent.

**shopware-mcp is that layer.** One small server that speaks MCP to the host
and the Admin API to the shop, and knows Shopware well enough to answer in one
call what used to take an afternoon in the admin:

| | |
|---|---|
| **Curated tools** | Products, orders and their history, documents, customers, categories, promotions, reviews, payment and shipping methods, plugins, stock, sales channels, scheduled tasks, the shop's trading settings: twenty tools that return compact JSON with exact totals, descriptions written for a model, and Shopware's own Criteria filters. No invented query language. |
| **An audit** | `shop_audit` runs sixteen checks in one call: paid orders that never shipped or never got an invoice, unpaid orders going stale, shipped orders never completed, products out of stock, running out at the current sales pace, without a cover, without a delivery time or invisible in every sales channel, promotions past their end date, channels in maintenance, storefronts missing a legal page, reviews waiting for moderation, scheduled tasks that stopped running, extensions with updates waiting, and which EU duties look covered by an installed extension. Prioritised, with samples and a hint per finding. The same audit runs as `shopware-mcp audit` from cron or CI, no MCP host needed. |
| **Reports and a forecast** | `sales_report` asks Shopware to aggregate: gross, net, average order, revenue per currency and channel, orders per state, a day/week/month timeline, the top products and, on request, the change against the period before. `customer_report` does the same for people: new accounts, guest share, repeat share, top customers by revenue. `stock_forecast` turns sales velocity and stock into days of cover, run-out dates and reorder quantities. The figures were checked against SQL on the same database. |
| **An escape hatch** | `entity_schema` describes any of the 200+ entities, a plugin's custom entities included, and `entity_search` queries them with the same filters and lets Shopware aggregate over the match: orders per payment method, revenue per month, anything a terms, sum or histogram can say. Entities that hold credentials are refused, secrets in the rest are scrubbed. |
| **A brake** | Read-only unless you start it with `--allow-write`. Even then every write is a dry run that shows the exact request first, and a write budget can cap how many real writes a process may make. Ship, mark paid, remind, refund, correct stock, note, generate a document, create a product or a promotion, give a product a picture, moderate a review, update a customer, invoice fifty orders in one go, tag a record: fifteen narrow writes, nothing else. Secrets never appear in output, logs or errors. |

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/brand/architecture-dark.svg">
    <img src="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/brand/architecture-light.svg" alt="An MCP host on the left, shopware-mcp in the middle, the Shopware 6 Admin API on the right. Tool calls flow right, compact JSON flows back." width="100%">
  </picture>
</p>

Shops are not identical, so the tool list is not either: at startup the server
looks up which extensions are installed and registers extra tools for the ones
it knows. A plain shop gets the core set. A shop with more plugins gets a bigger
agent, without configuration.

---

## See it work

<p align="center">
  <a href="https://bnymndev.github.io/shopware-mcp/#video">
    <img src="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/video/poster.jpg" alt="Thirty-second intro video: a real shop_audit answer in a terminal, the numbers, the safety model, how to install" width="100%">
  </a>
  <br>
  <sub>Thirty seconds, no sound: <a href="https://bnymndev.github.io/shopware-mcp/#video">watch on the website</a> or <a href="https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/video/shopware-mcp-intro.mp4">open the MP4</a>. Rendered from <a href="docs/video/">docs/video/</a>.</sub>
</p>

Every recording on this page is real output from the server against a Shopware
6.7.13 test shop with generated demo data, replayed from the transcripts in
[`docs/demo/`](docs/demo). Tool calls and results are verbatim, shortened to
fit the screen. The prose is what an MCP host says with them.

**One question, thirteen checks.** Three paid orders are still waiting for shipment,
the storefront is in maintenance, a summer promotion outlived August. The
answer names order numbers and amounts, and offers the safe next step.

![shop_audit: the agent asks one question, the tool returns prioritised findings with samples, the agent summarises them](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/audit.svg)

**Numbers the shop computed itself.** Totals, channels, states, a monthly
timeline and the top product for eight months, from one call. No order was
paged through; Shopware's aggregations did the work.

![sales_report: totals, revenue by channel, orders by state, a monthly timeline and top products](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/report.svg)

**No tool for that? There is a schema for that.** Manufacturers have no
dedicated tool. The agent reads the entity's schema, spots `mediaId`, and
filters on it. The same path reaches every other entity, custom ones included.

![entity_schema then entity_search: the agent discovers the mediaId field and finds 27 manufacturers without a logo](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/anything.svg)

**Writes show their hand first.** With `--allow-write`, a stock correction
comes back as the request it *would* send. Only an explicit `dryRun: false`
touches the shop, and the result is re-read from Shopware.

![stock_set: a dry run returns the PATCH it would send, the agent asks, the real write follows and returns the re-read product](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/write.svg)

**Ship it, then prove it.** A delivery transition is two requests, shown before
they are sent: the tracking code onto the delivery, then the state change. The
order's history afterwards names the transition, the states and who made it.

![order_delivery_transition then order_history: the dry run lists both requests, the write ships the order, the history shows the transition and the integration that made it](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/support.svg)

**A product and its launch code, from one sentence.** `product_create` picks
the shop's default tax and derives the net price, and says so in the dry run.
The promotion arrives inactive, so nobody sees a code before it was checked.

![product_create and promotion_create: the dry run shows the POST with tax and net price, the product is created, the promotion follows inactive](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/launch.svg)

**Moderation with a reply.** Two reviews wait for approval. The spam stays
hidden, the complaint is approved together with the shop's public answer, and
the model never had to touch the admin.

![reviews_search then review_moderate: two pending reviews, one approved with a reply after a dry run](https://raw.githubusercontent.com/bnymnDev/shopware-mcp/main/docs/demo/moderate.svg)

**People, not just revenue.** New accounts by group, how many customers
ordered and how many came back, the gues