Query and safely manage a Shopware 6 shop: products, orders, customers, stock, audits, reports.
io.github.bnymnDev/shopware-mcp (MCP Server)
The Model Context Protocol (MCP) server io.github.bnymnDev/shopware-mcp provides schema-aware access to a Shopware 6 shop. It supports querying and safely managing Shopware data, including products, orders, customers, stock, audits, reports, promotions, and plugins. It is read-only by default, and write operations require explicit confirmation with a dry run first.
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.
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.
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/. 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.
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.
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.
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.
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
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
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
People, not just revenue. New accounts by group, how many customers
ordered and how many came back, the guest share, and the top customers with
their share of the period, next to the period before.
customer_report: new customers, ordering and repeat customers, comparison with the previous period and the top customers by revenue
A shop with more plugins gets a bigger agent. The core tools are ready
immediately. The extension lookup finishes in the background, four tools appear,
the host is told to refresh its list, and a compliance question has an answer.
Reorder before it hurts.stock_forecast reads six months of line items
through one aggregation, joins them with the current stock, and says per
product how many days are left, when it hits zero, and how much to order. Nine
of these are already oversold; two are still fine today and will not be in
October.
stock_forecast: eleven products that run out within 60 days, with sales per day, days of cover, run-out date and a suggested reorder quantity
The same audit, no host in sight.shopware-mcp audit prints the findings
as Markdown and exits non-zero when something is critical (or, with
--fail-on warning, when anything is off). Put it in cron and read the mail;
put it in CI and let the job fail. shopware-mcp report does the same for the
numbers.
shopware-mcp audit and report on the command line: Markdown findings with exit code 1, then a monthly sales report table
A shop with an operations plugin gets an operations agent. FroshTools is the
open-source toolbox many Shopware hosters install. When it is there, three more
tools appear: the platform's health checks, the message queue with its worker,
and the dependency advisories. The agent tells stale search results apart from
a dead worker.
FroshTools pack: frosh_health lists the failing platform checks, frosh_queue shows 134 waiting messages and no worker, the agent names the cause
Fifty-six invoices, three at a time.order_documents_bulk_create finds the
paid orders that never got an invoice, oldest first, and shows the single request
that would create them before it does. Every order counts against the write
budget. Then scheduled_tasks_list explains how the backlog grew: 31 of 33
tasks overdue, none ever run, the scheduler is not running. tag_assign marks
the order for the team, creating the tag on the way.
order_documents_bulk_create dry run and apply for three orders, scheduled_tasks_list with 31 overdue tasks, tag_assign dry run creating the tag invoice-sent
Know before the agent finds out.shopware-mcp doctor probes what the integration may read, reads its role for the write privileges where it can, and names the missing one per tool. An administrator gets a wall of ticks; a support-desk role gets told exactly what to grant.
Screenshots from the MCP Inspector against the same shop
shop_settings reads the trading settings from Shopware's system configuration, shop-wide or per sales channel with inheritance: guest checkout, double opt-in, password rules, cart limits, listing defaults, default tax, legal pages. Only an allowlist of core domains; mail servers, licences and plugin secrets are never read.
Order history
order_history lists every order, payment and delivery transition of one order in sequence: previous state, new state, action, and whether an admin user, an API integration or Shopware itself triggered it.
Health audit
shop_audit with tunable thresholds (stuckOrderDays, lowStockThreshold, forecastDays, maxItems). Sixteen checks including paid orders without an invoice, products running out at the current pace, legal pages per storefront, delivery times, sales channel visibility, pending reviews and scheduled tasks that stopped running, prioritised findings, a hint per finding, and an EU duty overview that names duties and deadlines, never products.
Sales report
sales_report for any period, by day, week or month, optionally per sales channel, cancelled orders excluded. compareWithPrevious adds the preceding period and the change in orders, revenue and average order value. Top products resolved by exact product id so ties cannot skew revenue.
Customer report
customer_report for the same periods: new accounts split into registered and guest and by group, distinct ordering customers, repeat share, guest order share, and the top customers by revenue with their share of the total.
Stock forecast
stock_forecast for 'what do I need to reorder?': units sold per product in a window, current available stock, days of cover, the run-out date and a reorder quantity that covers the horizon plus a restock period. Nothing is estimated for products without sales.
Any entity
entity_schema lists all entities or describes one: fields, types, flags, associations. entity_search queries it, with Shopware aggregations (terms, sum, avg, min, max, count, stats, histogram, one nested metric) over the whole match on request. Long text values are truncated, secrets scrubbed, credential entities and credential fields refused.
Plugin-aware tools
The server detects installed, active extensions and adds tools for the ones it knows. Packs: FroshTools (platform health checks, message queue, dependency advisories) and Merqo. Off with --no-extensions.
Documents
order_documents_list, order_document_create (invoice, delivery note, credit note, cancellation, by Shopware's own generator), order_documents_bulk_create (one document type for up to fifty orders in one request, by default the paid orders that have none yet) and document_download, which hands the PDF to the host as an embedded resource while the model sees only the metadata.
Guarded writes
stock_set (absolute or delta), product_update, product_create, product_cover_set (a picture from a URL or bytes, uploaded by the shop), order_state_transition, order_delivery_transition (ship, with tracking codes), order_transaction_transition (mark paid, remind, refund), order_note (internal comment), order_document_create, order_documents_bulk_create, promotion_toggle, promotion_create, customer_update, review_moderate, tag_assign (tags by name on a customer, order or product; missing tags are created). Registered only with --allow-write, dryRun: true by default, the re-fetched entity on a real write. SHOPWARE_MCP_MAX_WRITES caps real writes per process, and a bulk call counts once per order.
A command line too
shopware-mcp doctor says per tool whether this integration can use it and which privilege is missing. shopware-mcp init tests the credentials and prints or writes the config for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI or Zed. shopware-mcp audit and shopware-mcp report print the audit and the sales report as Markdown or JSON, with exit codes for cron and CI.
Resources and prompts
shopware://shop, shopware://sales-channels, the templates shopware://order/{orderNumber}, shopware://product/{productNumber} and shopware://customer/{customerNumber} so a host can attach a record as context, and six prompts: order_summary, customer_profile, low_stock_report, reorder_list, review_moderation and weekly_review.
Shopware's vocabulary
Filters are Shopware Criteria filters (equals, contains, range, equalsAny) on Shopware field paths, including associations like manufacturer.name. State names are the technical names you already know.
Portable schemas
Every tool schema is checked to avoid constructs that some MCP clients misread, so the same server works in every host.
A solid client
OAuth client credentials with early token refresh, one retry on 401 and on 429/5xx with Retry-After, a per-request timeout, exact totals, inheritance and language headers, a cached entity schema.
Two transports
stdio for desktop hosts, stateless Streamable HTTP for everything else, with an optional bearer token.
Packaged four ways
npm with build provenance, a Docker image on GHCR for amd64 and arm64, a one-click .mcpb bundle for Claude Desktop that asks for the credentials and a write budget, and a listing in the official MCP registry.
Who it is for
You run a shop and want to ask it questions instead of clicking through the admin. Stuck orders, low stock, last month's numbers, one prompt each.
You run an agency and look after many shops. The core here covers one shop per server; the multi-shop, audited, hosted version is what the author builds for clients (see Open core).
You build Shopware plugins and want your custom entities reachable by an agent today, and your own tools registered tomorrow. entity_search does the first; one file under src/extensions/ does the second.
You build agents and want an MCP server that behaves: compact output, honest totals, dry runs, no surprises in the schema.
60 seconds
1. Create an Integration in your Shopware admin: Settings → System → Integrations → Add integration. Copy the access key ID and the secret; the secret is shown once. For a dev shop tick Administrator, for production give it a read role (see permissions).
2. Let the wizard test the credentials and write the host config for you:
bash
npx shopware-mcp init # asks for URL, key and secret, tests them, prints the config
npx shopware-mcp init --for claude-desktop --write # or merges it into the host's config file
npx shopware-mcp doctor # which tools can this integration use, and what is missing
npx shopware-mcp audit --fail-on warning # the shop audit as Markdown, exit 1 when something is off
npx shopware-mcp report --interval week # the sales report of the last 30 days as Markdown
Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI, Zed and other stdio hosts
They all take the same three fields. Cursor reads .cursor/mcp.json, VS Code .vscode/mcp.json (under servers instead of mcpServers), Windsurf ~/.codeium/windsurf/mcp_config.json, Gemini CLI ~/.gemini/settings.json, Codex CLI a [mcp_servers.shopware] table in ~/.codex/config.toml, Zed its context_servers block. init --for <host> --write writes each of them:
The image serves Streamable HTTP on http://127.0.0.1:3333/mcp. Point any HTTP-capable host at that URL. Add -e SHOPWARE_MCP_HTTP_TOKEN=<random secret> and the endpoint requires Authorization: Bearer <secret>; without a token, keep it on localhost or behind a proxy that authenticates (self-hosting notes).
4. Ask. The first useful question is usually "Is everything okay with the shop?"
Ask it anything
You say
The agent calls
"Is everything okay with the shop?"
shop_audit
"How did we do in August?"
sales_report { from, to, interval: "week" }
"Which products are below 5 in stock?"
products_search with a range filter, or the low_stock_report prompt
"Summarise order 10042 for a support reply."
orders_get, or the order_summary prompt
"Which customers ordered more than ten times?"
customers_search with a range filter on orderCount
"Is the PayPal plugin up to date?"
plugins_list
"Which manufacturers have no logo?"
entity_schema then entity_search on product_manufacturer
"Set the stock of SW10084 to 40."
stock_set, dry run first, then for real
"Order 10042 shipped with DHL, tracking 00340434."
Anything you can filter in the Admin API works here too, associations included.
Need a raw field that the compact output leaves out, such as customFields,
ean or weight? Pass fields: ["customFields", "ean"] and it is added to
every item. Reading a shop in another language? Set SHOPWARE_LANGUAGE_ID.
The full cheat sheet has more.
Every parameter of every tool: docs/tools.md. Searches return
{ total, page, limit, items } with exact totals, limit is capped at 50, and
errors come back as { error: { status, code, detail } } so the model can
react instead of guessing.
At startup the server asks the shop which extensions are installed and active,
in the background, and registers extra tools for the ones it knows. A shop that
does not answer simply keeps the core tools. --no-extensions turns the whole
mechanism off.
Two packs ship today. FroshTools,
the open-source operations plugin, adds frosh_health (platform health and
performance checks), frosh_queue (message queue transports, waiting messages,
worker) and frosh_composer_audit (dependency advisories); all read-only, the
plugin's own maintenance actions are never called. Merqo
adds merqo_health, merqo_einvoice_inbox, merqo_returns_search and
merqo_abandoned_carts. Shops without a plugin never see its tools, and nothing
in the core tools changes either way. Support for another vendor's extensions
is one file under src/extensions/, tested against the installed plugin; pull
requests are welcome.
Safety
Read-only by default. Without --allow-write (or SHOPWARE_MCP_ALLOW_WRITE=true) the write tools are not registered. An agent cannot discover what it cannot call.
Every write is a dry run first. All fifteen write tools, from stock_set to tag_assign, default to dryRun: true and return { dryRun: true, wouldSend: { method, url, body } }, a list when one call needs several requests. A real write returns the re-fetched entity.
A write budget.SHOPWARE_MCP_MAX_WRITES=20 refuses the twenty-first real write of a process with WRITE_BUDGET_EXHAUSTED; dry runs stay free. No prompt can lift it.
Narrow writes.product_update touches name, description, active and one currency's price; product_create makes a simple product and nothing else; product_cover_set adds one picture (JPEG, PNG, WebP, GIF or AVIF, never SVG) that the shop itself downloads. promotion_create creates one cart discount, inactive unless told otherwise. customer_update touches the active flag and the group. The transition tools only move state machines; nothing moves money. Documents come from Shopware's own generator and are never sent by this server; order_documents_bulk_create makes at most fifty per call and charges the write budget once per order. tag_assign adds or removes tags by name and leaves the rest of the record alone. Nothing deletes. Nothing else is writable.
Scrubbed reads.entity_search strips passwords, keys, tokens and hashes from every payload and refuses entities that exist to hold credentials or system internals: users, integrations, ACL roles, apps, system config.
No secrets anywhere. Credentials never appear in output, logs or error messages. Logs go to stderr only, at error level unless you ask for more.
No telemetry. The server talks to your shop and to your host. Nothing else.
HTTP transport. Set SHOPWARE_MCP_HTTP_TOKEN and every call to /mcp needs that bearer token, compared in constant time. Without it, bind to localhost (the default) or put it behind a reverse proxy that authenticates; the server warns when it is reachable further without a token.
Requests time out. A shop that stops answering costs one request 30 seconds (SHOPWARE_MCP_TIMEOUT_MS), not the whole session.
Shop base URL, e.g. https://shop.example.com (trailing slash is stripped)
SHOPWARE_CLIENT_ID
yes
Integration access key ID
SHOPWARE_CLIENT_SECRET
yes
Integration secret access key
SHOPWARE_MCP_ALLOW_WRITE
no
true registers the write tools. Default: off
SHOPWARE_MCP_MAX_WRITES
no
Real writes one process may perform in total; 0 (default) means no cap
SHOPWARE_MCP_DEFAULT_LIMIT
no
Default page size for search tools (default 20, max 50)
SHOPWARE_MCP_EXTENSIONS
no
false disables plugin-aware tools and the extension lookup at startup
SHOPWARE_LANGUAGE_ID
no
Language UUID for translated fields (sw-language-id). Default: shop default language
SHOPWARE_MCP_TIMEOUT_MS
no
Per-request timeout for the Admin API in milliseconds (default 30000, 1000 to 600000)
SHOPWARE_MCP_HTTP_TOKEN
no
Bearer token the HTTP transport requires on /mcp (at least 16 characters). Default: none
SHOPWARE_MCP_LOG_LEVEL
no
error (default), warn, info, debug. Logs go to stderr only
CLI flags override the environment: --allow-write, --max-writes <n>, --no-extensions, --http, --port <n>, --host <addr>, --log-level <level>. Commands: doctor [--json] and init [--for <host>] [--write].
The Integration needs read permissions on the entities you query and write
permissions on product, order and promotion for the write tools. Administrator
is the quick path for a dev shop; use a dedicated role in production
(which permissions).
Design principles
Shopware's vocabulary, not ours. Filters, field paths, state names and entity names are Shopware's. A tool call reads like the Admin API request it becomes, and a Shopware developer needs no second dictionary.
Compact by default, complete on request. Items carry what a model needs to reason and page. Raw fields come with fields, more rows with page, and long text is truncated rather than dumped.
Reading is free, writing is explicit. Write tools exist only when asked for, default to a dry run, and return the exact request. The model sees the consequence before the shop does.
Let the shop do the maths. Totals, timelines and top products are Shopware aggregations with exact counts, not client-side sums over pages.
Vendor-neutral core. Extension packs live in their own files, are registered only when the shop has the extension, and never change how the core tools behave. No telemetry, no phone-home.
Everything in this repository is MIT and stays that way. It covers one shop, one operator, interactive use.
The same author builds Merqo, a commercial suite of Shopware
extensions for EU compliance and daily operations. This server detects them and adds matching
tools, but it never requires them, and the core tools behave the same either way.
Agencies and merchants running this at scale usually need more, and that is what I build and operate for clients:
Multi-shop: one MCP endpoint that routes to dozens of shops with per-shop credentials and permissions
Hosted with audit trail: every tool call logged with who, what and when, role-based access, SLA
Bulk operations and migrations: mass price and stock updates, catalogue imports, safe rollbacks
Custom agents and Shopware plugins: workflows tailored to your ERP, PIM or support desk
Interested? Open an issue with the consulting label or reach out via github.com/bnymnDev. Using shopware-mcp in production and want it to stay maintained? Sponsoring helps.
Building from source
bash
pnpm install
pnpm dev # stdio server via tsx
pnpm test# vitest + msw-mocked Admin API
pnpm build # tsup → dist/ (npm) and dist/bundle/ (self-contained)
pnpm pack:mcpb # Claude Desktop bundle → shopware-mcp.mcpb
pnpm inspect # MCP Inspector against dist/
pnpm docs:tools # regenerate docs/tools.md and the tool tables in both READMEs
pnpm docs:demos # re-render the recordings in docs/demo/ from their transcripts
End-to-end tests against a real Shopware (dockware/dev, or any shop you point them at) run with pnpm test:e2e; see CONTRIBUTING.md.
Status
v0.4. Everything on this page is implemented, covered by unit tests against
mocked Admin API responses, and exercised nightly end-to-end against a real
Shopware. The recordings above come from Shopware 6.7.13; 6.6 is supported too.
Not in it, on purpose: user management for the HTTP transport (one static
token, or a proxy), multi-shop routing and audit trails (the commercial part),
and write tools beyond the fifteen that a support desk and a shop manager need on a normal day.
Ideas that fit: more extension packs, better error hints for common Shopware
ACL problems, a products_search example gallery. The good first
issues
are a fine place to start.
