如何通过 MCP 将 Shopware 6 Admin API 连接到 Gemini

💡 无需安装? 直接使用 cloud.anythingmcp.com。 登录、点击 Connectors → Shopware 6 Admin API、粘贴凭证、生成 MCP API key，即可完成。无 Docker、无 git clone、无本地服务器。

Shopware 6 Admin API + Gemini

Shopware 6 Admin API，即商店的后台 API（不是 Store API）：搜索任意实体，维护商品、分类、细到单个插槽的 Shopping Experiences 布局和媒体库，读取销售渠道、促销和 SEO URL。通用写入、删除和批量同步在安装时关闭。

前提条件

完整的设置说明已内置在连接器中 (在 store 中选择连接器时可见)。所需环境变量:

SHOPWARE_URL, SHOPWARE_ACCESS_KEY_ID, SHOPWARE_SECRET_ACCESS_KEY

步骤 1 — 获取凭证

是 Admin API，不是 Store API：此连接器使用 Shopware 6 商店的 Admin API（/api），也就是 Shopware Administration 自身用来管理商店的 API：商品、分类、Shopping Experiences 布局和媒体库。它与 Shopware 6 Store API（shopware-6）是不同的连接器，后者用销售渠道的访问密钥读取公开店面。需要让 AI 处理商店的后台管理数据时，请安装这个连接器。

设置大约需要 3 分钟。你需要能访问该商店的 Shopware Administration。

1. 在 Shopware Administration 中打开 Settings > System > Integrations，新建一个集成。
2. 为它命名，然后打开 Administrator 开关，或分配一个具有 AI 所需权限的角色。如果角色只能读取，所有写入工具都会以 403 失败。
3. 把 Access key ID（以 SWIA 开头）复制到 SHOPWARE_ACCESS_KEY_ID，把 Secret access key 复制到 SHOPWARE_SECRET_ACCESS_KEY。密钥只显示一次；丢失后请在集成中新建密钥。
4. 把 SHOPWARE_URL 设为不带路径的商店地址，例如 https://shop.example.com。不要加 /api 或 /admin。
5. 安装连接器并运行 shopware_6_admin_get_version：它会显示 Shopware 版本并确认凭据可用。

AnythingMCP 通过 OAuth2 客户端凭据授权在商店的 /api/oauth/token 获取短期有效的 Bearer 令牌，并自动续期。

可读取的内容：可全文搜索并筛选的商品（商品编号、启用状态、库存、制造商、分类、属性、通过 parentId 区分的变体），以及单个商品自身的字段（名称、编号、库存、价格、描述、SEO 字段、自定义字段）；分类及其父分类、位置、类型、布局、启用和可见标志以及面包屑；Shopping Experiences 布局（CMS 页面），以及单个布局的区块、块和插槽，包括每个插槽的 config；媒体库及其 URL、文件名、替代文本、标题和文件夹；销售渠道及其域名（Store API 访问密钥会从响应中移除）；促销及其代码、有效期和使用次数限制；SEO URL。其他任何 Admin API 实体，例如订单、客户、制造商、属性组和属性选项、规则、语言、货币或文本片段，都通过 shopware_6_admin_search_entities 和 shopware_6_admin_get_entity 读取。

搜索条件：每个搜索工具都接受 Shopware 的 criteria：term、ids、filter（equals、equalsAny、contains、prefix、suffix、range、not、multi）、sort、associations、includes、limit、page 和 total_count_mode；商品和通用搜索还接受 aggregations。关联字段用点路径筛选，例如 categories.id 或 manufacturer.name。完整的商品数据很大，因此 AI 在不需要完整记录时会传入 includes。ID 是 32 个不带连字符的十六进制字符；AI 通过搜索工具查找 ID，从不猜测。

语言和变体：文本按语言翻译。传入 language_id（作为 sw-language-id 请求头发送）时，读取返回该语言的翻译，写入修改该语言的翻译；不传则使用商店的系统语言。用 shopware_6_admin_search_entities 并指定实体 language 可列出语言。新记录先用系统语言创建。变体是带有 parentId 的商品，会从父商品继承空字段；inheritance: true 会显示继承的值。

可写入的内容：shopware_6_admin_update_product（文本、SEO 字段、自定义字段、启用标志、库存、清仓、EAN、价格；价格会替换整个价格列表）、shopware_6_admin_add_product_property 和 shopware_6_admin_remove_product_property（只关联或解除关联一个属性选项）、shopware_6_admin_create_property_option、shopware_6_admin_create_category 和 shopware_6_admin_update_category（包括在分类树中移动分类）、shopware_6_admin_create_cms_page、shopware_6_admin_update_cms_page（带 id 的区块、块和插槽会被更新，不带 id 的会被添加，不会删除任何内容）、shopware_6_admin_create_cms_block、shopware_6_admin_update_cms_slot（config 会替换该语言下插槽的 config）、先 shopware_6_admin_create_media 再 shopware_6_admin_upload_media_from_url、shopware_6_admin_update_media 和 shopware_6_admin_create_media_folder。这些工具在安装时即开启，会修改正在运行的商店：商店缓存刷新后，顾客就能看到变化。通过 URL 上传需要 Shopware 的 enable_url_upload_feature（默认开启）和公开 URL，并会替换媒体条目中已有的文件。

安装时关闭：shopware_6_admin_create_entity、shopware_6_admin_update_entity（任意实体，包括订单、客户、销售渠道和设置）、shopware_6_admin_delete_entity（永久删除，相关记录可能被一并删除）和 shopware_6_admin_sync（通过 Sync API 批量 upsert 和删除）。由工作区管理员有意开启。

响应：更新、上传和删除返回空的 204，因此 AI 会重新读取记录来确认修改。创建类工具返回带 id 的新记录。列表返回 total、data 和 aggregations。

限制：Shopware 默认每页最多 500 条结果；AI 用 page 翻页。total_count_mode 为 1 时返回精确总数，为 2 时只返回是否还有下一页。

常见错误：401 表示 Access key ID 或密钥错误：重新复制两者，或在集成中新建密钥。403 表示集成的角色无权执行此操作：打开 Administrator 或扩展角色权限。每次调用都返回 404，通常表示 SHOPWARE_URL 中包含 /api、/admin 或其他路径。

使用安装时开启的工具，连接器不会创建或修改订单、客户或设置，也不会删除任何内容。它只从公开 URL 上传媒体，不从你的电脑上传。如需用销售渠道访问密钥读取公开店面，请使用 Shopware 6 Store API 连接器。

步骤 2 — 安装 adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

步骤 3 — 在 Gemini 中添加连接器

你的服务器 URL： 在 AnythingMCP 中打开 MCP Servers → 此连接器所在的服务器，复制它的 URL（https://cloud.anythingmcp.com/mcp/…）。本指南中出现 YOUR_SERVER_ID 的地方都用它替换。

Gemini CLI 从 ~/.gemini/settings.json（Windows 上为 %USERPROFILE%\.gemini\settings.json）读取 MCP 服务器。添加：

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. 在 AnythingMCP 的 MCP Servers → 你的服务器 → API keys 中创建 MCP API 密钥，并用它替换 YOUR_MCP_API_KEY。
2. 保存文件并重启 gemini。
3. 在 Gemini CLI 中运行 /mcp（或在终端运行 gemini mcp list），anythingmcp 应显示为已连接。
4. 开始输入提示，Gemini CLI 现在可以调用 Shopware 6 Admin API 的工具。

可用工具

示例提示

• “找出所有库存少于 5 件的启用商品，显示商品编号、名称和库存。”
• “用德语和英语重写商品 SW10001 的 meta title 和 meta description。保存前先给我看文本。”
• “显示我们夏季落地页的 Shopping Experiences 布局，包括区块、块和插槽。”
• “把 https://example.com/banner.jpg 的图片上传到媒体文件夹 Banners，并设置替代文本。”
• “现在有哪些促销处于启用状态？列出它们的代码和有效期。”

FAQ

Gemini CLI 从哪里读取 MCP 服务器？ 用户级配置位于 ~/.gemini/settings.json，项目级配置位于项目内的 .gemini/settings.json。gemini mcp list 会列出每个服务器及其连接状态。

下一步

• 连接器主页
• 连接到 Claude
• 连接到 ChatGPT
• 连接到 Cursor
• 连接到 Meta Muse
• 连接到 Microsoft Copilot