shopware mcp

Why · Demo · Install · Tools · Safety · Docs · Deutsch

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:

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

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, nine 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.

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.

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.

What's in the box

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:

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

Or run the server by hand:

export SHOPWARE_URL=https://shop.example.com
export SHOPWARE_CLIENT_ID=SWIA...
export SHOPWARE_CLIENT_SECRET=...

npx shopware-mcp                       # stdio (default)
npx shopware-mcp --http --port 3333    # Streamable HTTP on http://127.0.0.1:3333/mcp
npx shopware-mcp --allow-write         # also register the guarded write tools

3. Connect a host (or let init --write do it):

{
  "mcpServers": {
    "shopware": {
      "command": "npx",
      "args": ["-y", "shopware-mcp"],
      "env": {
        "SHOPWARE_URL": "https://shop.example.com",
        "SHOPWARE_CLIENT_ID": "SWIA...",
        "SHOPWARE_CLIENT_SECRET": "..."
      }
    }
  }
}

claude mcp add shopware \
  -e SHOPWARE_URL=https://shop.example.com \
  -e SHOPWARE_CLIENT_ID=SWIA... \
  -e SHOPWARE_CLIENT_SECRET=... \
  -- npx -y shopware-mcp

{
  "mcpServers": {
    "shopware": {
      "command": "npx",
      "args": ["-y", "shopware-mcp"],
      "env": {
        "SHOPWARE_URL": "https://shop.example.com",
        "SHOPWARE_CLIENT_ID": "SWIA...",
        "SHOPWARE_CLIENT_SECRET": "..."
      }
    }
  }
}

docker run --rm -p 3333:3333 \
  -e SHOPWARE_URL=https://shop.example.com \
  -e SHOPWARE_CLIENT_ID=SWIA... -e SHOPWARE_CLIENT_SECRET=... \
  ghcr.io/bnymndev/shopware-mcp

4. Ask. The first useful question is usually "Is everything okay with the shop?"

Ask it anything

Filters, in one screen

Every search tool takes the same filter array, and every entry is a Shopware Criteria filter:

{ "type": "equals",    "field": "active",                                    "value": true }
{ "type": "range",     "field": "stock",                                     "value": { "lt": 5 } }
{ "type": "range",     "field": "orderDateTime",                             "value": { "gte": "2026-06-01" } }
{ "type": "equals",    "field": "transactions.stateMachineState.technicalName", "value": "paid" }
{ "type": "contains",  "field": "name",                                      "value": "shirt" }
{ "type": "equalsAny", "field": "id",                                        "value": ["…", "…"] }
{ "type": "equals",    "field": "manufacturer.name",                         "value": "Acme" }

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.

Tools

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.

Resources: shopware://shop, shopware://sales-channels, shopware://order/{orderNumber}, shopware://product/{productNumber}. Prompts: order_summary, low_stock_report, weekly_review.

Plugin-aware tools

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.

Today one suite is supported, Merqo, which adds merqo_health, merqo_einvoice_inbox, merqo_returns_search and merqo_abandoned_carts. Shops without it never see those tools, and nothing in the core tools changes either way. Support for another vendor's extensions is one file under src/extensions/; 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. stock_set, product_update, order_state_transition, order_delivery_transition, order_transaction_transition, order_note, order_document_create and promotion_toggle 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. The transition tools only move state machines; nothing moves money. Documents come from Shopware's own generator and are never sent by this server. 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.

Found something? See SECURITY.md.

Configuration

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

1. 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.
2. 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.
3. 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.
4. Let the shop do the maths. Totals, timelines and top products are Shopware aggregations with exact counts, not client-side sums over pages.
5. 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.

The reasoning behind individual choices is in docs/decisions.md.

Documentation

Open core

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

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.3. 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 eight that a support desk needs 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.

License

MIT

_{If shopware-mcp answered a question your admin could not, a star helps the next shop find it.}