# @acodera/shopify-admin-mcp 中文文档

规范地址：https://npmcn.com/package/%40acodera/shopify-admin-mcp/

版本：1\.11\.0
npm 元数据更新时间：2026-10-15T04:48:04.414Z
中文译文更新时间：2026-11-06T18:38:56.196Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40acodera/shopify-admin-mcp
原文对照：https://npmcn.com/package/%40acodera/shopify-admin-mcp/?lang=original
项目主页：https://github.com/acoderacom/shopify-admin-mcp#readme
源码仓库：https://github.com/acoderacom/shopify-admin-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：459 kB，112 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：5 个
- 首次发布：2026-10-09T10:38:37.599Z
- 最新版本发布：2026-10-15T04:48:04.055Z
- 近 30 天下载量：2468（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

MCP 服务器提供对 Shopify 的 Admin GraphQL API 的全程访问 , 并带有 chema introduction

## 安装

```sh
npm install @acodera/shopify-admin-mcp
```

也可以使用：`pnpm add @acodera/shopify-admin-mcp`、`yarn add @acodera/shopify-admin-mcp`、`bun add @acodera/shopify-admin-mcp`

## README

# 购物- admin- mcp

[![npm](https://img.shields.io/npm/v/@acodera/shopify-admin-mcp)](https://www.npmjs.com/package/@acodera/shopify-admin-mcp) [![CI](https://github.com/acoderacom/shopify-admin-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/acoderacom/shopify-admin-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://npmcn.com/package/%40acodera/shopify-admin-mcp/LICENSE)

用于 Shopify 的 Admin GraphQL API 的 MCP 服务器: 用于常见存储任务的打入工具, 用于其它所有工作的原始 GraphQL , 以及现场的 schema 搜索, 所以您的 AI 助手会针对您的存储服务的 API 进行工作 。 目标 API 版本 **2026-10 (英语)**。 。 。 .

## 特征

-   **59个便利工具** 产品、收藏、出版、元场、元对象、客户、订单、库存、折扣、文件、主题和市场
-   **Raw GraphQL 和 现场计划搜索** 任何工具都无法覆盖
-   **本地文件夹的主题文件**: 与 `--theme-dir`,主题书写文件时用文件名发送文件,并使用一个拉动工具复制文件,因此文件内容不必通过对话
-   **设置向导** 写着 `.mcp.json` 给你的
-   **安全控制**:只读模式、工具、现场主题守护、限制本地上传、每个工具只读或破坏性说明
-   **两种认证方法**: Dev Dashboard 客户端证书(自动更新)和遗产 `shpat_` 符号
-   **了解费率限制**: 节奏请求等待成本桶重新填充, 然后重试

## 快速启动

在您的工程文件夹中运行设置向导 :

```bash
npx -y @acodera/shopify-admin-mcp@latest setup
```

它运行在macOS,Linux和Windows上. 它检查你的节点Js版本,然后问设置什么:

-   **只连接到商店**: 要求您的商店和证书, 检查它们, 选择添加 [购买 Dev MCP](https://shopify.dev/docs/apps/build/devmcp) 服务器,并创建或更新 `.mcp.json`。主题编辑关闭(`--disable-theme-writes`),因此助理可以读取主题,但不能改变;其他一切,如产品和元场,都可以被改变. 本地文件, 如产品图像, 上传自 `./uploads`,它创造了,除非 `.mcp.json` 已经设置了上传文件夹.
-   **带有地平线的全部主题设计**: 也下载了 Shopify 的 [地平线](https://github.com/Shopify/horizon) 主题进入 `./theme` 写作 `CLAUDE.md`, (中文(简体) ), `THEME.md` 财务报告和审定财务报表 `customizations.md` 从 [acoderacom/claude-视距](https://github.com/acoderacom/claude-horizon),将商店和现场主题填入 `CLAUDE.md`切换到什么 `CLAUDE.md` 描述: 现场主题写入, 主题文件来自 `./theme`上传 `./uploads`和Shofify Dev MCP。 。 。 商店的活生生主题必须是模板支持的地平线版本(列于其 `versions.json`),项目得到了准确的版本. 否则设置会显示要切换到哪个版本, 不写就停止 `.mcp.json`。由于 Shopify 主题商店只安装最新的地平线,它提供保存上传准备 `horizon-<version>.zip` 页:1 **在线存储 主题 添加主题 ~ 上传 zip 文件**。 。 。 .
-   **完整主题编辑站点**:因为在没有"地平线"支票的情况下,在现场商店的主题"地平线"(Horizon)的复制上工作. 第一次复制 Shopify 管理员中的活版主题(**网上存储 = 主题 = 复制**)并给抄本取名. 设置列出商店的主题,并取出副本克洛德编辑;直播主题列出但无法取出,如果商店没有副本则设置停止. 直播主题写出不动, 主题被锁定( L)`--lock-themes`),因此服务器拒绝任何对活版主题的修改,也拒绝任何主题创建,复制,重命名,删除或发布:您自己发布副本. 设置写入 `CLAUDE.md` (没有模拟规则)和 `customizations.md` 从模板 `live-site/` 包含存储和副本名称、版本和所填ID的文件夹,空白 `THEME.md`空时 `./theme`。然后用手:下载副本(**• 下载主题文件**打开它 `./theme`,并且,当你想要的时候,请克洛德学习这个主题:它写着 `THEME.md` 从 `./theme`,在那之前,它一直保持空白。 与现场共享产品和菜单等存储数据,因此其更改仍然同时显示; `CLAUDE.md` 克劳德先问 继续运行设置 `./theme`, (中文(简体) ), `THEME.md` 和所选的副本,除非你修改它们.

当前值被预填并保留了其他服务器. 设置不问另一个 [选项](https://npmcn.com/package/%40acodera/shopify-admin-mcp/#readme-configuration),例如只读模式、工具或原始 GraphQL;设置在 `.mcp.json` 手边。 运行“ 仅连接到商店” 保留它们; 两种主题设计模式都设置了 `CLAUDE.md` 取决于。 秘密以纯文本保存, 因此文件被添加到 `.gitignore` 在git repo中,在macOS和Linux上,只有你才能读取。 Windows没有这样的文件模式,因此文件获得其文件夹的权限: 将工程保留在用户文件夹内,其他用户无法读取. 重新启动 Claude 代码( 或运行) `/mcp`要连接.

### 手动设置

克劳德代码:

```bash
claude mcp add shopify \
  -e SHOPIFY_STORE=mystore.myshopify.com \
  -e SHOPIFY_CLIENT_ID=your_client_id \
  -e SHOPIFY_CLIENT_SECRET=your_client_secret \
  -- npx -y @acodera/shopify-admin-mcp
```

或进入 `.mcp.json`,或 Claude 桌面配置(`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上, `%APPDATA%\Claude\claude_desktop_config.json` 视窗上 :

```json
{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["-y", "@acodera/shopify-admin-mcp"],
      "env": {
        "SHOPIFY_STORE": "mystore.myshopify.com",
        "SHOPIFY_CLIENT_ID": "${SHOPIFY_CLIENT_ID}",
        "SHOPIFY_CLIENT_SECRET": "${SHOPIFY_CLIENT_SECRET}"
      }
    }
  }
}
```

对于一个遗产的标志,设置 `SHOPIFY_ACCESS_TOKEN` 而不是客户身份和秘密 Claude 代码扩展 `${VAR}` 从你的外壳,所以 `.mcp.json` claude Desktop不这样做,所以直接将数值写在那里.

## 认证

-   **客户证书(建议):** 在其中创建应用程序 [底盘](https://dev.shopify.com/dashboard),配置下面的瞄准镜,发布一个版本,安装在您的商店,并使用它的客户端ID和秘密. 应用程序和商店必须属于同一商店组织。 托肯持续了24小时,并自动刷新.
-   **在浏览器中获得批准:** 在应用程序组织外的商店安装的应用程序,例如客户端的商店或你作为合作者接触到的商店,在那里,Shopify拒绝客户端的证书 `shop_not_permitted`在设置中,选择 **在浏览器中批准的客户端身份和秘密**。它会打印一个重定向 URL, `http://localhost:3457/auth/callback`,在Dev Dashboard中添加应用软件的版本(当时发布版本),打开Shorpify的审批页面,并交换对一个离线访问令牌的批准,该令牌持续到应用程序未安装或其秘密被旋转为止. 客户秘密只用于批准; `.mcp.json` 获取访问符.
-   **遗产访问符 :** 页:1 `shpat_` 现有自定义应用程序的标志.

只授予您使用的工具范围 :

| 范围 | 工具 |
| --- | --- |
| `read_products`, (中文(简体) ), `write_products` | 产品、变种、收藏 |
| `read_publications`, (中文(简体) ), `write_publications` | 出版 |
| `read_metaobjects`, (中文(简体) ), `write_metaobjects` | 元对象条目 |
| `read_metaobject_definitions`, (中文(简体) ), `write_metaobject_definitions` | 元对象定义 |
| 拥有资源的范围 | 梅塔菲尔德斯(例如. `read_products` 用于产品元场) |
| `read_customers`, (中文(简体) ), `write_customers` | 客户 |
| `read_orders` (+ 数) `read_all_orders` 超过60天的订单) | 命令 |
| `read_inventory`, (中文(简体) ), `write_inventory`, (中文(简体) ), `read_locations` | 库存 |
| `read_discounts`, (中文(简体) ), `write_discounts` | 贴现 |
| `read_files`, (中文(简体) ), `write_files` | 文件 |
| `read_themes`, (中文(简体) ), `write_themes` (+ 写作的主题码豁免) | 主题 |
| `read_markets`, (中文(简体) ), `write_markets` | 市场 |

客户姓名、电子邮件、电话号码和地址 [受保护的客户数据](https://shopify.dev/docs/apps/launch/protected-customer-data),您的应用程序也必须被批准.

## 工具

总是可用 : `shopify_graphql` (任何查询或突变;仅以只读模式查询), `shopify_schema_search`,以及 `shopify_schema_details`。其余部分归为工具,全部默认注册:

| 工具集 | 工具( 每个前缀) `shopify_`(中文(简体) ) |
| --- | --- |
| `products` | `products_list`, (中文(简体) ), `product_get`, (中文(简体) ), `product_create`, (中文(简体) ), `product_update`, (中文(简体) ), `product_delete`, (中文(简体) ), `product_variants_create`, (中文(简体) ), `product_variants_update` |
| `collections` | `collections_list`, (中文(简体) ), `collection_get`, (中文(简体) ), `collection_create`, (中文(简体) ), `collection_update`, (中文(简体) ), `collection_delete` |
| `publishing` | `publications_list`, (中文(简体) ), `publish`, (中文(简体) ), `unpublish` |
| `metafields` | `metafields_list`, (中文(简体) ), `metafields_set`, (中文(简体) ), `metafield_delete`, (中文(简体) ), `metafield_definitions_list`, (中文(简体) ), `metafield_definition_create` |
| `metaobjects` | `metaobject_definitions_list`, (中文(简体) ), `metaobject_definition_create`, (中文(简体) ), `metaobjects_list`, (中文(简体) ), `metaobject_get`, (中文(简体) ), `metaobject_create`, (中文(简体) ), `metaobject_update`, (中文(简体) ), `metaobject_upsert`, (中文(简体) ), `metaobject_delete` |
| `customers` | `customers_list`, (中文(简体) ), `customer_get`, (中文(简体) ), `customer_update` |
| `orders` | `orders_list`, (中文(简体) ), `order_get` |
| `inventory` | `inventory_get_levels`, (中文(简体) ), `inventory_adjust` |
| `discounts` | `discounts_list`, (中文(简体) ), `discount_get`, (中文(简体) ), `discount_amount_off_create`, (中文(简体) ), `discount_free_shipping_create`, (中文(简体) ), `discount_bxgy_create`, (中文(简体) ), `discount_activate`, (中文(简体) ), `discount_deactivate`, (中文(简体) ), `discount_delete`, (中文(简体) ), `discount_codes_add` |
| `files` | `files_list`, (中文(简体) ), `file_upload`, (中文(简体) ), `file_delete` |
| `themes` | `themes_list`, (中文(简体) ), `theme_files_list`, (中文(简体) ), `theme_files_get`, (中文(简体) ), `theme_files_upsert`, (中文(简体) ), `theme_files_delete`, (中文(简体) ), `theme_duplicate`, (中文(简体) ), `theme_delete`· ; `theme_files_pull` 与 `--theme-dir` |
| `markets` | `markets_list`, (中文(简体) ), `market_get`, (中文(简体) ), `market_create`, (中文(简体) ), `market_update`, (中文(简体) ), `market_delete` |

少数投入跟随API 2026-10:收藏用 `sources` (见 `CollectionCreateSourceTargetInput` 内 `shopify_schema_details`, (中文(简体) ), `shopify_inventory_adjust` 需要您在变化前所期望的数量(`changeFromQuantity`),而折扣需要一种资格(`customerIds`, (中文(简体) ), `customerSegmentIds`,或 `marketIds`按收集或产品分列的物品,而不是两者兼有.

## 本地文件夹中的主题文件

主题文件通常先被编辑为主题的本地副本. 发送文件内容通过 `shopify_theme_files_upsert` 让助理写出整个文件, 需要几分钟的时间一个大部分。 与 `--theme-dir` 指向本地副本:

-   `shopify_theme_files_upsert` 仅发送其文件 `filename` 从文件夹中取出:文本为正文,其他内容为 Base64 。 当Shoppify的写作完成后,它会报告每个文件是否按照发送的方式存储. shopify regenerates JSON 文件,如模板(添加其头并重命名它们),因此它返回的文件被替换到文件夹中,取而代之的是shopify的副本.
-   `shopify_theme_files_pull` 复制文件或图案,例如 `sections/*` 从主题进入文件夹中,每个调用最多50个,只返回文件名和校验和。 已经匹配的文件被单独处理 .

通过的文件 `content`, (中文(简体) ), `contentBase64` 或者说 `url` 像以前一样工作.

## 安全问题

-   **只读模式** (单位:千美元)`--read-only`)只登记在原始图形QL中读取数据并拒绝突变的工具。 文档是解析的,因此注释或额外操作不能滑出一个. 每当助手不需要更改店面时使用:产品说明和客户通知书由他人撰写并可以携带说明.
-   **工具集** (单位:千美元)`--toolsets products,orders`) 缩短工具列表,但原始 GraphQL 仍然可以到达任何您允许的范围 。 添加 `--disable-raw-graphql` 以保留选定工具的助手。 无论哪种方式,应用的瞄准镜都是真正的极限.
-   **现场主题** 被保护:主题文件写作并删除已发布文件(`MAIN`)主题被拒绝,包括通过原始 GraphQL,其中 `themePublish` 也被拒绝。 复制主题,编辑副本,并从 Shopify 管理员处发布,或从 `--allow-live-theme-writes`。 。 。 .
-   **主题编辑** 可以完全关闭 `--disable-theme-writes`:主题写作工具被忽略,而原始的GraphQL拒绝每个主题突变(文件写作, `themeCreate`, (中文(简体) ), `themeUpdate`, (中文(简体) ), `themeDelete`, (中文(简体) ), `themeDuplicate`, (中文(简体) ), `themePublish`任何它的目标主题。 它能覆盖 `--allow-live-theme-writes`,并设置"连接到一个商店"模式打开.
-   **主题可以锁定** 与 `--lock-themes`:主题文件仍然可以编辑,但 `shopify_theme_duplicate` 财务报告和审定财务报表 `shopify_theme_delete` 被忽略, 原始 GraphQL 拒绝 `themeCreate`, (中文(简体) ), `themeDuplicate`, (中文(简体) ), `themeUpdate`, (中文(简体) ), `themeDelete` 财务报告和审定财务报表 `themePublish`,因此复制品不能被删除或更名,任何内容都不能出版. 设置"Full主题编辑现场"模式开启.
-   **主题文件夹** (单位:千美元)`--theme-dir`)是唯一一个发送并被拉入的地方主题文件. 引出其外的路径, 包括同义链接, 以及主题本身文件夹外的文件 (`assets`, (中文(简体) ), `blocks`, (中文(简体) ), `config`, (中文(简体) ), `layout`, (中文(简体) ), `locales`, (中文(简体) ), `sections`, (中文(简体) ), `snippets`, (中文(简体) ), `templates`)被拒绝.
-   **本地上传** 离开直到你开始 `--upload-dir` (设置设备) `./uploads` 在两种模式中). `shopify_file_upload` 然后接受该文件夹内的文件(symlinks solved),以及Shopify自取的公共URL.
-   **全权证书** 只有寄给 `*.myshopify.com`,服务器会在秘密被作为旗帜传递时发出警告,因为其他进程可以看到它们.

## 配置

每个选项在软件包名称后( 在 `args`)或作为环境变量(在 `env`:

| 旗帜 | 环境变量 | 默认 | 说明 |
| --- | --- | --- | --- |
| `--store` | `SHOPIFY_STORE` | 所需经费 | `mystore` 或者说 `mystore.myshopify.com` |
| `--access-token` | `SHOPIFY_ACCESS_TOKEN` |  | 遗产 `shpat_` 符号 |
| `--client-id` | `SHOPIFY_CLIENT_ID` |  | 客户证书 ID |
| `--client-secret` | `SHOPIFY_CLIENT_SECRET` |  | 客户证书秘密 |
| `--api-version` | `SHOPIFY_API_VERSION` | `2026-10` | `YYYY-MM` 或者说 `unstable` |
| `--toolsets` | `SHOPIFY_TOOLSETS` | 全部 | 要注册的逗号分隔工具 |
| `--upload-dir` | `SHOPIFY_UPLOAD_DIR` | 关 | 本地上传限制的绝对路径 |
| `--theme-dir` | `SHOPIFY_THEME_DIR` | 关 | 本地主题副本的绝对路径, 主题文件来自并被拉入 |
| `--read-only` | `SHOPIFY_READ_ONLY` | 关 | 只读工具, 没有突变 |
| `--allow-live-theme-writes` | `SHOPIFY_ALLOW_LIVE_THEME_WRITES` | 关 | 允许写入并发布实况主题 |
| `--disable-theme-writes` | `SHOPIFY_DISABLE_THEME_WRITES` | 关 | 拒绝每个主题更改; 覆盖 `--allow-live-theme-writes` |
| `--lock-themes` | `SHOPIFY_LOCK_THEMES` | 关 | 保留主题文件编辑但拒绝创建、复制、重命名、删除和发布主题 |
| `--disable-raw-graphql` | `SHOPIFY_DISABLE_RAW_GRAPHQL` | 关 | 别管了 `shopify_graphql` |

例如: `"args": ["-y", "@acodera/shopify-admin-mcp", "--read-only", "--toolsets", "products,orders,customers"]`。 。 。 .

-   启用/关闭变量接受 `true` 或者说 `1`。当一个选项被双向设定时,旗帜将获胜;对于上下选项,要么打开.
-   空白值和未填入的引用( E)`${VAR}`, (中文(简体) ), `$VAR`) 计为未设置,所以一个配置可以列出两种认证方法. 如果两者都填入,则使用访问符.
-   使用绝对 `--upload-dir` 财务报告和审定财务报表 `--theme-dir`,因为MCP客户端从自己的工作目录启动服务器.
-   和一个老人 `--api-version`,原始 GraphQL 有用,但有些工具可能不行。 如果 Shostify 服务与请求的版本不同, 服务器会登录警告 .

## Schema 勘探公司

服务器在连接后对背景中的活生生的策略进行回顾. `shopify_schema_search` 按关键词查找类型、查询和变异,以及 `shopify_schema_details` 显示类型字段或操作的参数。 折旧的字段被排除在外,这可以引导助手向目前的API方向前进.

## 发展

```bash
git clone https://github.com/acoderacom/shopify-admin-mcp.git
cd shopify-admin-mcp && git checkout dev && npm install
npm run build   # or `npm run dev` to rebuild on change
npm test        # unit tests; live tests skip themselves without credentials
npm run lint    # type-check src and tests
```

需要节点js 22.12 或以后。 设置 `SHOPIFY_STORE` 并进行现场测试 `SHOPIFY_TEST_WRITES=1` 运行创建然后删除的写入测试 `[MCP test]` 数据,所以只用一个开发商店.

为捐款,分行从 `dev`,添加一个更改器 `npx changeset` (文件、测试或CI不需要) `dev`。版本合并 `dev` 输入 `main`;然后工作流程打开一个 **版本软件包** 拉取请求,并将其合并到 npm 通过 [值得信赖的出版](https://docs.npmjs.com/trusted-publishers) 与出处.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40acodera/shopify-admin-mcp/LICENSE)。 。 。 .

最初创建于 [科尔比·麦克亨利](https://github.com/colbymchenry) 作为 [商店名称- ql- admin- mcp](https://github.com/colbymchenry/shopify-graphql-admin-mcp),并由 [编码通讯](https://github.com/acoderacom)。 。 。 .

## 常见问题

### @acodera/shopify-admin-mcp 是什么？

MCP 服务器提供对 Shopify 的 Admin GraphQL API 的全程访问 , 并带有 chema introduction

### 如何安装 @acodera/shopify-admin-mcp？

在项目目录运行 npm install @acodera/shopify-admin-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 shopify-admin-mcp，可以用 npx shopify-admin-mcp 直接运行。

### @acodera/shopify-admin-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @acodera/shopify-admin-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @acodera/shopify-admin-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @acodera/shopify-admin-mcp 可以商用吗？

@acodera/shopify-admin-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @acodera/shopify-admin-mcp 的下载量有多少？

根据 npm 官方下载统计，@acodera/shopify-admin-mcp 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,468 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @acodera/shopify-admin-mcp 还在维护吗？

最新版本 1\.11\.0 发布于 2026/10/15（23 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/10/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。