shopware-mcp

为什么 · 演示 · 安装 · 工具 · 安全性 · 文档 · 网站 · Deutsch

介绍 shopware-mcp

Shopware 6 商店的一个 Admin API 背后有大约两百种实体。问助手“商店一切正常吗？”，要诚实地回答，就得用 Criteria 筛选器搜索七次，按技术名称操作三个状态机，做几次聚合，还需要一个绝不能原样复述给你的 OAuth 令牌。把模型直接连到这个 API，它就能访问所有内容，包括因为提示词这么说而 PATCH 价格的权限。

模型上下文协议让“给模型真正的工具”变成了一行配置更改。但它没有说明一个好的商店工具应该是什么样：两百种实体里哪些在周二早上最重要、“卡住的订单”是什么意思，或者库存更正应该在发送前先展示出来。

**shopware-mcp 就是这一层。**一个小型服务，通过 MCP 与主机通信，通过 Admin API 与商店通信；它足够了解 Shopware，能够一次调用就回答过去要在管理后台花一下午才能查清的问题。它还会留意订单何时停止进来，并像顾客一样尝试结账，以找出原因：

看看实际效果

六小时没有订单，原因何在。 周日傍晚。脉搏会将这段沉寂与过去八个周日的同一时段进行比较，而这些时段总会带来 3 到 7 笔订单，并得出纯属巧合的概率约为 170 分之一。随后，Agent 会像顾客一样尝试购买，结果发现店面处于维护模式。没有下单，也没有任何更改。

顾客眼中的结账体验。 一位瑞士顾客表示优惠码无法使用。通过 Shopware 自有的 Store API 创建一个临时购物车，一次解释了这两个问题：瑞士不是该销售渠道覆盖的国家，而且该优惠码的促销活动已于 8 月结束。随后，搜索功能解释了为什么某件商品始终没有显示。

每天早晨，一页概览。 shopware-mcp brief --html brief.html 会将脉搏、审计结果和过去 7 天的数据写入一个独立页面，不会从任何位置加载内容，并会跟随读者的深色模式。可通过 cron 运行，并使用 --slack 在频道中发送一段摘要。 打开实际示例。

一条命令，实现最小权限。 shopware-mcp setup 只需以管理员身份登录一次，即可创建一个权限恰好满足工具所需的角色；这些权限是根据实际商店测得的，而非猜测得出。它还会创建一个非管理员集成。该命令只显示一次密钥，会验证二者并打印主机配置。升级后再次运行，它会更新角色，同时保留密钥。

_{30 秒，无声播放：在网站上观看或打开 MP4。由 docs/video/ 渲染。}

本页中的所有录制内容，均为服务在带有生成式演示数据的 Shopware 6.7.13 测试商店中运行时产生的真实输出，并根据 docs/demo/ 中的记录重放。工具调用和结果均为原文，仅为适应屏幕而缩短。周围的文字则是 MCP 主机根据这些内容生成的。

一个问题，一次调用。 三笔已付款订单仍在等待发货，店面处于维护状态，一项夏季促销活动已延续至 8 月之后。答案列出了订单号和金额，并提供了安全的下一步操作。

由店铺自行计算的数据。 一次调用即可获取总计、渠道、状态、月度时间线和八个月以来的热门产品。无需逐个翻查订单；Shopware 的聚合功能完成了这项工作。

没有对应的工具？那就有对应的架构。 制造商没有专用工具。Agent 会读取实体的架构，找到 mediaId，并据此筛选。同样的方式适用于其他所有实体，包括自定义实体。

写入操作会先展示具体内容。 使用 --allow-write 后，库存更正会以其将要发送的请求形式返回。只有明确设置 dryRun: false 才会修改店铺，之后还会从 Shopware 重新读取结果。

先发货，再验证。 配送状态变更需要两个请求，发送前会先展示：先将跟踪码添加到配送信息，再更改状态。之后，订单历史会列出该状态变更、涉及的状态以及执行者。

一句话创建产品及其推广代码。 product_create 会选用店铺的默认税率并计算未税价格，同时在试运行中说明这一点。促销活动创建时处于未激活状态，因此在审核完成前，没有人会看到代码。

审核并回复。 有两条评价待审批。垃圾内容会继续隐藏；投诉会在获批的同时附上店铺的公开回复，模型完全无需操作管理后台。

关注客户，而不只是收入。 按分组统计新增账户、下单客户和回头客数量、访客占比，以及贡献期内收入份额最高的客户，并与上一期对比。

插件越多，店铺的 Agent 能力越强。 核心工具立即可用。扩展查询在后台完成后，会新增四个工具，并通知宿主刷新工具列表；之后，合规问题也能得到解答。

趁问题还没发生，及时补货。 stock_forecast 通过一次聚合读取六个月的订单明细，与当前库存合并后，逐个产品说明还剩多少天的库存、何时会售罄，以及需要订购多少。有九种产品已经超卖；另外两种目前仍然充足，但到了 10 月就不再如此。

同样的审计，无需主机介入。 shopware-mcp audit 会以 Markdown 格式输出发现的问题，并在存在严重问题时以非零状态码退出（或者使用 --fail-on warning 时，只要有任何异常就会退出）。将它加入 cron，然后查看邮件；将它加入 CI，让任务失败。shopware-mcp report 也会以同样的方式处理数据。

安装了运维插件的商店，也能获得运维 Agent。 FroshTools 是许多 Shopware 托管服务商都会安装的开源工具箱。安装后会出现另外三个工具：平台健康检查、带有工作进程的消息队列，以及依赖项安全公告。Agent 能区分过时的搜索结果和已停止运行的工作进程。

一次处理 56 张发票，每次 3 张。 order_documents_bulk_create 会按从早到晚的顺序查找已付款但尚未开具发票的订单，并在执行前显示将要创建发票的单个请求。每个订单都会计入写入预算。然后，scheduled_tasks_list 会说明积压是如何形成的：33 个任务中有 31 个逾期，从未运行过，调度器也没有运行。tag_assign 会为团队标记订单，并在过程中创建标签。

先了解情况，再让 Agent 去发现。 shopware-mcp doctor 会探测集成可以读取的内容，在可能的情况下读取其角色以检查写入权限，并列出每个工具缺少的权限。管理员会看到满屏的勾选标记；支持台角色则会收到明确说明，知道需要授予哪些权限。

包含内容

适用对象

• 你经营一家商店，希望通过提问来获取信息，而不是在管理后台中逐项点击。订单卡住了、库存不足、上个月的数字——每项只需一个提示词。
• 你经营一家代理机构，负责管理许多商店。这里的核心功能是每个服务对应一家商店；作者为客户打造的多商店、经过审计且托管的版本，请参阅开放核心。
• 你开发 Shopware 插件，希望 Agent 今天就能访问你的自定义实体，明天还能注册自己的工具。entity_search 实现前者；在 src/extensions/ 下添加一个文件即可实现后者。
• 你构建 Agent，希望 MCP 服务行为可靠：输出精简、总数准确、支持试运行，架构中没有意外。

60 秒上手

1. 让 setup 创建集成。它会以管理员身份登录一次（密码绝不会被保存），创建一个仅含工具所需权限的只读角色，再创建使用该角色的集成，验证两者，并打印或写入主机配置：

npx shopware-mcp setup --url https://shop.example.com --user admin --for claude-desktop --write

添加 --allow-write 以启用写入工具，添加 --settings 以启用 shop_settings；--dry-run 会先显示该角色的权限。升级后再次运行同一命令：它会更新角色并保留密钥。想自己操作？在 Settings → System → Integrations 下创建集成，为其分配一个角色（参阅权限），然后继续执行第 2 步。

2. 或者让向导测试现有凭据并为你写入主机配置：

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
npx shopware-mcp brief --html brief.html   # pulse, audit and the last 7 days as one HTML page

也可以手动运行服务：

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. 连接主机（或让 init --write 来完成）：

{
  "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. 开始提问。通常第一个有用的问题是 “商店一切正常吗？”

随便问它什么

一屏了解筛选器

每个搜索工具都使用相同的 filter 数组，其中每个条目都是 Shopware Criteria 筛选器：

{ "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" }

Admin API 中可筛选的内容在这里也都适用，包括关联。 需要紧凑输出中未包含的原始字段，例如 customFields、 ean 或 weight？传入 fields: ["customFields", "ean"]，这些字段就会添加到 每个项目中。需要用其他语言读取商店？设置 SHOPWARE_LANGUAGE_ID。 完整内容请参阅速查表。

工具

资源：shopware://shop、shopware://sales-channels、shopware://order/{orderNumber}、shopware://product/{productNumber}。提示词：order_summary、low_stock_report、weekly_review。

支持插件的工具

服务启动时会在后台查询商店，获取已安装并启用的扩展，并为其已识别的扩展注册额外工具。商店若未响应，则只保留核心工具。--no-extensions 会关闭整个机制。

目前提供两个工具包。FroshTools 是一个开源运维插件，可添加 frosh_health（平台健康状况和性能检查）、frosh_queue（消息队列传输、待处理消息、工作进程）和 frosh_composer_audit（依赖项安全公告）；这些工具均为只读，不会调用插件自身的维护操作。Merqo 可添加 merqo_health、merqo_einvoice_inbox、merqo_returns_search 和 merqo_abandoned_carts。未安装插件的商店不会看到其对应工具，核心工具也不会因此发生任何变化。要支持其他厂商的扩展，只需在 src/extensions/ 下添加一个文件，并针对已安装的插件进行测试；工具包会列出其插件路由所需的 ACL 权限，安装该插件后，shopware-mcp setup 会授予这些权限。欢迎提交拉取请求。

安全

• 默认只读。 未设置 --allow-write（或 SHOPWARE_MCP_ALLOW_WRITE=true）时，不会注册写入工具。Agent 无法发现自己无法调用的工具。
• 每次写入都先进行试运行。 全部 15 个写入工具，从 stock_set 到 tag_assign，默认采用 dryRun: true，并返回 { dryRun: true, wouldSend: { method, url, body } }；如果一次调用需要发送多个请求，则返回请求列表。实际写入会返回重新获取的实体。
• 写入额度。 SHOPWARE_MCP_MAX_WRITES=20 会拒绝进程中的第 21 次实际写入，并返回 WRITE_BUDGET_EXHAUSTED；试运行不计入额度。任何提示词都无法提高此额度。
• 限制写入范围。 product_update 只会修改名称、描述、启用状态和一种货币的价格；product_create 只会创建简单商品，不做其他操作；product_cover_set 会添加一张图片（JPEG、PNG、WebP、GIF 或 AVIF，不接受 SVG），由商店自身下载。promotion_create 会创建一项购物车折扣，除非另有指定，否则设为未启用。customer_update 只会修改启用标记和分组。状态转换工具只会推进状态机，不会转移资金。文档由 Shopware 自带的生成器生成，本服务不会发送文档；order_documents_bulk_create 每次调用最多生成 50 份文档，并按每个订单计收一次写入额度。tag_assign 会按名称添加或移除标签，不会改动记录的其他部分。不会删除任何内容。其他内容均不可写入。
• 模拟购物车不是订单。 checkout_simulate 和 storefront_search 会通过 Shopware 自带的管理代理访问 Store API，并使用访客无法持有的随机上下文令牌。不会调用订单路由，之后会删除购物车；留下的只有一条上下文记录，Shopware 会自行使其过期。以客户身份进行模拟不会触及该客户自己的会话或已保存的购物车。会对已保存购物车做出响应的扩展（例如弃购邮件发送器）会将模拟购物车视为该客户的购物车，因此只有在可以接受的情况下，才以真实客户身份进行模拟。
• 默认遵循最小权限原则。 shopware-mcp setup 会根据针对一个除此之外不具备任何权限的角色进行的测量，为每个工具授予其所需的确切权限，且绝不授予管理员权限。有两项权限的范围超出其对应工具，除非你主动请求，否则不会授予：读取整个系统配置，包括 SMTP 密码和支付密钥（--settings）；以及安装扩展（--plugin-updates）。Setup 只会更改其创建的角色，会列出添加或移除的每项权限，并会在任何其他环节可能失败之前显示新的密钥。管理员密码仅用于通过 https 登录一次；仅连接本机时也可使用纯 http，并且绝不会保存该密码。
• 读取内容会清理敏感信息。 entity_search 会从每个负载中移除密码、密钥、令牌和哈希值，并拒绝访问用于存放凭据或系统内部信息的实体：用户、集成、ACL 角色、应用、系统配置。
• 任何地方都不会出现密钥。 凭据绝不会出现在输出、日志或错误消息中。日志只写入 stderr，级别为 error，除非你要求更详细的日志。
• 不收集遥测数据。 服务只会与商店及你的主机通信，不会与其他对象通信。
• HTTP 传输。 设置 SHOPWARE_MCP_HTTP_TOKEN 后，每次调用 /mcp 都必须携带该 bearer token，并会以恒定时间进行比较。未设置该令牌时，请绑定到 localhost（默认设置），或将服务置于经过身份验证的反向代理之后；如果服务在没有令牌的情况下可从更广范围访问，就会发出警告。
• 请求会超时。 如果商店停止响应，单个请求最多耗时 30 秒（SHOPWARE_MCP_TIMEOUT_MS），不会拖垮整个会话。

发现了问题？请参阅 SECURITY.md。

配置

CLI 标志优先于环境变量：--allow-write、--max-writes <n>、--no-extensions、--http、--port <n>、--host <addr>、--log-level <level>。命令包括：setup、doctor、init、brief、audit 和 report；npx shopware-mcp --help 会列出它们的选项。

集成需要对工具涉及的实体拥有读取权限，并为写入工具拥有写入权限。shopware-mcp setup 会精确授予这些权限；对于开发商店，使用 Administrator 是快捷方式（所需权限）。

设计原则

1. 使用 Shopware 的术语，而非我们自己的术语。 筛选条件、字段路径、状态名称和实体名称均采用 Shopware 的术语。工具调用看起来就像它实际转换成的 Admin API 请求，Shopware 开发者无需再记一套术语。
2. 默认精简，按需完整。 条目包含模型进行推理和分页所需的信息。使用 fields 获取原始字段，使用 page 获取更多行；长文本会被截断，而非直接倾倒出来。
3. 读取无需额外设置，写入则需明确启用。 写入工具仅在用户提出要求时才会启用，默认执行试运行，并返回确切请求。商店执行操作前，模型就能看到其后果。
4. 让商店负责计算。 总计、时间线和热门商品都通过 Shopware 聚合得出精确数量，而非在客户端对分页结果求和。
5. 核心与供应商无关。 扩展包各自存放在独立文件中，仅在商店安装了对应扩展时才会注册，且绝不会改变核心工具的行为。不收集遥测数据，也不会向外发送数据。

各项具体设计选择的原因见 docs/decisions.md。

文档

开源核心

本仓库中的所有内容均采用 MIT 许可，并将始终如此。它面向一家店铺、一个运营人员和交互式使用场景。

同一作者还开发了 Merqo，这是一套面向欧盟合规和日常运营的商业 Shopware 扩展套件。本服务会检测这些扩展并添加相应工具，但从不要求必须安装它们；无论是否安装，核心工具的行为都一样。

大规模运营的代理机构和商家通常需要更多功能，这正是我为客户构建和运营的内容：

• 多店铺：一个 MCP 端点即可路由到数十家店铺，并为每家店铺配置独立的凭据和权限
• 托管服务与审计跟踪：记录每次工具调用的人员、操作和时间，提供基于角色的访问控制及 SLA
• 批量操作与迁移：批量更新价格和库存、导入商品目录、安全回滚
• 定制 Agent 和 Shopware 插件：针对你的 ERP、PIM 或支持平台定制工作流

有兴趣吗？请创建带有 consulting 标签的 issue，或通过 github.com/bnymnDev 联系我。在生产环境中使用 shopware-mcp，并希望它持续得到维护？赞助会有所帮助。

从源代码构建

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

针对真实 Shopware（dockware/dev，或你指定的任意店铺）运行端到端测试，请使用 pnpm test:e2e；参见 CONTRIBUTING.md。

状态

v0.8。本页列出的所有内容均已实现，经过针对模拟 Admin API 响应的单元测试，并且每晚都会针对真实 Shopware 进行端到端测试。上方的录制内容来自 Shopware 6.7.13；也支持 6.6。

有意不包含的功能：HTTP 传输的用户管理（使用一个静态令牌，或通过代理实现）、多店铺路由和审计跟踪（商业功能），以及超出支持团队和店铺经理日常所需的 15 种写入工具之外的其他写入工具。

适合添加的点子：更多扩展包、用通俗语言解释更多购物车错误、products_search 示例图库。适合新手的 issue是不错的起点。

许可证

MIT

_{如果 shopware-mcp 回答了管理员无法解答的问题，点个星可以帮助其他店铺找到它。}