Shopify GraphQL MCP服务器

一个模型上下文协议（MCP）服务器，通过cURL提供对Shopify Admin GraphQL API的全面访问。该服务器将所有主要的Shopify资源公开为MCP工具，允许Claude等人工智能助手以编程方式与您的Shopify商店交互。

🚧 项目状态：该项目目前正在积极开发中。新的工具和功能正在定期添加。

由...创建：犹他州奥勒姆犹他谷大学的学生

先决条件

Node.js 18+
npm或纱线
具有管理员API访问权限的Shopify商店
Shopify Admin API访问令牌

安装

1.克隆或创建项目

git clone 
cd shopify-graphql-mcp

2.安装依赖项

npm install

3.构建服务器

npm run build

配置

环境变量

创建一个 .env 文件或设置这些环境变量：

SHOPIFY_ACCESS_TOKEN=shpat_xxxxx
SHOPIFY_STORE_URL=your-store.myshopify.com
SHOPIFY_STORE_API_URL=https://your-store.myshopify.com/admin/api/2025-01/graphql.json

工具类别（建议与IDE兼容）

此MCP服务器提供 150+工具 涵盖Shopify的所有业务。一些IDE对工具数量有限制，因此您可以通过以下方式启用/禁用工具类别 ENABLED_TOOL_CATEGORIES 环境变量：

类别	描述	~工具计数	模块
`essential`	核心电子商务：产品、订单、客户、库存	~35	店铺、产品、订单，客户、库存、收款、地点、订单草稿、折扣、履行
`commerce`	扩展商务：礼品卡、退货、结账、B2B	~25	礼品卡、退款、结账、付款条件、订单编辑、公司、现金跟踪、履行约束、交付定制、交付选项生成器、定制履行服务
`marketing`	营销：营销活动、市场、分析、渠道	~20	营销活动、营销市场、渠道、发现、价格规则、分析、像素、出版物
`content`	内容：页面、主题、文件、元对象	~25	页面、导航、主题、文档、元对象、翻译、区域设置、法律政策
`advanced`	高级：购物车转换、验证、脚本	~20	购物车转换，验证、审计事件、自定义像素、脚本标签、客户数据擦除、客户合并、客户支付方式、隐私设置、运输、产品列表
`reporting`	报告和反馈	~15	报告、资源反馈、应用程序
`automation`	库存自动化	~15	库存发货、库存转移、装箱单模板

推荐配置：

// Minimal - Essential only (~35 tools) - Best for most users
{
  "env": {
    "ENABLED_TOOL_CATEGORIES": "essential"
  }
}

// Standard - Essential + Commerce (~60 tools)
{
  "env": {
    "ENABLED_TOOL_CATEGORIES": "essential,commerce"
  }
}

// Marketing Focus - Essential + Marketing (~55 tools)
{
  "env": {
    "ENABLED_TOOL_CATEGORIES": "essential,marketing"
  }
}

// Full Power User (~105 tools)
{
  "env": {
    "ENABLED_TOOL_CATEGORIES": "essential,commerce,marketing,content"
  }
}

// Everything (~155 tools) - May overwhelm some IDEs
{
  "env": {
    "ENABLED_TOOL_CATEGORIES": "all"
  }
}

默认行为： 如果 ENABLED_TOOL_CATEGORIES 未设置， 所有类别均已启用 （向后兼容）。

IDE兼容性：

光标：建议使用约100-150个工具
克劳德桌面：支持约200多种工具
泽德：建议使用~50-75个工具

看工具_CATEGORIES.md 以获取完整的文档。

获取您的访问令牌

详细的OAuth设置说明

首选设置 > 应用 > 开发应用程序 > 在开发人员仪表板中构建应用程序
进入开发人员仪表板后，单击 创建应用程序 并输入应用程序名称（例如“Shopify GraphQL MCP”），然后单击创建
使用 http://localhost:9292 对于应用程序URL
在下面添加以下范围范围 > 访问:

read_all_orders,read_analytics,read_app_proxy,write_app_proxy,read_apps,read_assigned_fulfillment_orders,write_assigned_fulfillment_orders,read_audit_events,read_customer_events,read_cart_transforms,write_cart_transforms,read_all_cart_transforms,read_validations,write_validations,read_cash_tracking,write_cash_tracking,read_channels,write_channels,read_checkout_branding_settings,write_checkout_branding_settings,write_checkouts,read_checkouts,read_companies,write_companies,read_custom_fulfillment_services,write_custom_fulfillment_services,read_custom_pixels,write_custom_pixels,read_customers,write_customers,read_customer_data_erasure,write_customer_data_erasure,read_customer_payment_methods,read_customer_merge,write_customer_merge,read_delivery_customizations,write_delivery_customizations,read_price_rules,write_price_rules,read_discounts,write_discounts,read_discounts_allocator_functions,write_discounts_allocator_functions,read_discovery,write_discovery,write_draft_orders,read_draft_orders,read_files,write_files,read_fulfillment_constraint_rules,write_fulfillment_constraint_rules,read_fulfillments,write_fulfillments,read_gift_card_transactions,write_gift_card_transactions,read_gift_cards,write_gift_cards,write_inventory,read_inventory,write_inventory_shipments,read_inventory_shipments,write_inventory_shipments_received_items,read_inventory_shipments_received_items,write_inventory_transfers,read_inventory_transfers,read_legal_policies,write_legal_policies,read_delivery_option_generators,write_delivery_option_generators,read_locales,write_locales,write_locations,read_locations,read_marketing_integrated_campaigns,write_marketing_integrated_campaigns,write_marketing_events,read_marketing_events,read_markets,write_markets,read_markets_home,write_markets_home,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders,read_metaobject_definitions,write_metaobject_definitions,read_metaobjects,write_metaobjects,read_online_store_navigation,write_online_store_navigation,read_online_store_pages,write_online_store_pages,write_order_edits,read_order_edits,read_orders,write_orders,write_packing_slip_templates,read_packing_slip_templates,write_payment_mandate,read_payment_mandate,read_payment_terms,write_payment_terms,read_payment_customizations,write_payment_customizations,read_pixels,write_pixels,read_privacy_settings,write_privacy_settings,read_product_feeds,write_product_feeds,read_product_listings,write_product_listings,read_products,write_products,read_publications,write_publications,read_purchase_options,write_purchase_options,write_reports,read_reports,read_resource_feedbacks,write_resource_feedbacks,read_returns,write_returns,read_script_tags,write_script_tags,read_shopify_payments_provider_accounts_sensitive,read_shipping,write_shipping,read_shopify_payments_accounts,read_shopify_payments_payouts,read_shopify_payments_bank_accounts,read_shopify_payments_disputes,write_shopify_payments_disputes,read_content,write_content,read_store_credit_account_transactions,write_store_credit_account_transactions,read_store_credit_accounts,write_own_subscription_contracts,read_own_subscription_contracts,write_theme_code,read_themes,write_themes,read_third_party_fulfillment_orders,write_third_party_fulfillment_orders,read_translations,write_translations,customer_read_companies,customer_write_companies,customer_write_customers,customer_read_customers,customer_read_draft_orders,customer_read_markets,customer_read_metaobjects,customer_read_orders,customer_write_orders,customer_read_quick_sale,customer_write_quick_sale,customer_read_store_credit_account_transactions,customer_read_store_credit_accounts,customer_write_own_subscription_contracts,customer_read_own_subscription_contracts,unauthenticated_write_bulk_operations,unauthenticated_read_bulk_operations,unauthenticated_read_bundles,unauthenticated_write_checkouts,unauthenticated_read_checkouts,unauthenticated_write_customers,unauthenticated_read_customers,unauthenticated_read_customer_tags,unauthenticated_read_metaobjects,unauthenticated_read_product_pickup_locations,unauthenticated_read_product_inventory,unauthenticated_read_product_listings,unauthenticated_read_product_tags,unauthenticated_read_selling_plans,unauthenticated_read_shop_pay_installments_pricing,unauthenticated_read_content

使用 http://localhost:9292/auth/callback 对于重定向URL
点击发布
发布后，导航到设置对于应用程序
使用 客户端ID 和秘密提供凭据后，在浏览器中打开此URL：

https://admin.shopify.com/store//oauth/authorize?client_id=&scope=&redirect_uri=http%3A%2F%2Flocalhost:9292%2Fauth%2Fcallback&state=nonce-12345

这将返回一个URL，如下所示：

http://localhost:9292/auth/callback?code=&hmac=&host=&shop=.myshopify.com&state=nonce-12345&timestamp=

复制 `` 从返回的URL中获取值，然后在终端中运行以下命令：

curl -X POST "https://.myshopify.com/admin/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "",
    "client_secret": "",
    "code": ""
  }'

这将返回您将在MCP配置文件中使用的Shopify访问令牌（例如MCP.json）。

快速设置（现有应用程序）

如果您已经有一个具有所需范围的应用程序：

登录您的Shopify管理员
首选设置 > 应用程序和销售渠道 > 开发应用程序
创建新应用程序或使用现有应用程序
点击 配置管理员API作用域
选择所需的范围（请参阅下面的“所需范围”部分）
将应用程序安装到您的商店
复制 管理员API访问令牌

MCP客户端配置

将此服务器添加到您的MCP客户端配置中（例如，Claude Desktop、Cursor）：

macOS/Linux（推荐-仅限基本工具）：

{
  "mcpServers": {
    "shopify-graphql": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/shopify-graphql-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_STORE_API_URL": "https://your-store.myshopify.com/admin/api/2025-01/graphql.json",
        "ENABLED_TOOL_CATEGORIES": "essential"
      }
    }
  }
}

窗户：

{
  "mcpServers": {
    "shopify-graphql": {
      "command": "node",
      "args": ["C:\\PATH\\TO\\shopify-graphql-mcp\\dist\\index.js"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_STORE_URL": "your-store.myshopify.com",
        "SHOPIFY_STORE_API_URL": "https://your-store.myshopify.com/admin/api/2025-01/graphql.json",
        "ENABLED_TOOL_CATEGORIES": "essential"
      }
    }
  }
}

可用工具

此MCP服务器提供 150+工具 分为7类。有关所有可用工具的完整列表，请参阅 工具_CATEGORIES.md 文件。

工具类别

类别	描述	~工具数量
必要的	核心电商：产品、订单、客户、库存	~35
商业	扩展商务：礼品卡、退货、结账、B2B	~25
营销	营销：活动、市场、分析、渠道	~20
内容	内容：页面、主题、文件、元对象	~25
高级	高级：购物车转换、验证、脚本	~20
报告	报告和反馈	~15
自动化	库存自动化	~15

看工具_CATEGORIES.md 以获取完整的工具参考。

使用示例

获取订单

"Get the last 10 orders from my store"

创建产品

"Create a new product called 'Summer T-Shirt' with a $29.99 price"

更新库存

"Set the inventory for variant ID gid://shopify/ProductVariant/123 to 100 at location ID gid://shopify/Location/456"

获取分析

"Show me my store's total sales for last month using ShopifyQL"

营销活动

"Create a marketing event for our summer sale starting next week"

内容管理

"Create a new page called 'About Us' with our company story"

发展

项目结构

shopify-graphql-mcp/
├── src/
│   ├── index.ts              # Server entry point
│   ├── tools/                # Tool implementations organized by category
│   │   ├── index.ts         # Tool registration and category management
│   │   ├── orders.ts
│   │   ├── products.ts
│   │   ├── customers.ts
│   │   └── ... (50+ tool modules)
│   ├── config/
│   │   └── tool-categories.ts  # Category configuration
│   ├── utils/
│   │   ├── graphql-client.ts
│   │   └── scope-mapper.ts
│   └── types/
│       └── index.ts
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
├── TOOL_CATEGORIES.md       # Detailed category documentation
└── README.md

添加新工具

在相应的类别文件中定义工具 src/tools/
使用 server.registerTool() 模式
包括输入的Zod模式验证
优雅地处理错误
将工具添加到中的类别配置中 src/config/tool-categories.ts

例子：

server.registerTool(
  "my_new_tool",
  {
    description: "Description of what this tool does",
    inputSchema: {
      param1: z.string().describe("Parameter description"),
    },
  },
  async ({ param1 }) => {
    // Implementation
  }
);

建筑

npm run build

类型检查

npm run typecheck

故障排除

未找到环境变量

确保设置了所有三个环境变量：

SHOPIFY_ACCESS_TOKEN
SHOPIFY_STORE_URL
SHOPIFY_STORE_API_URL

工具类别不起作用

检查 health_check 工具输出，查看启用了哪些类别：

"Run health check to see my server status"

GraphQL错误

检查您的访问令牌是否具有您尝试执行的操作所需的作用域。

未找到cURL

确保您的系统上安装了cURL：

# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Windows
curl is included in Windows 10+

权限被拒绝（macOS/Linux）

确保编译后的文件是可执行的：

chmod +x dist/index.js

安全说明

永远不要承诺你的 SHOPIFY_ACCESS_TOKEN 到版本控制
使用环境变量或安全密钥管理器
访问令牌提供对您的商店的完全API访问-确保其安全
考虑为不同的环境（开发、测试、生产）使用单独的令牌

所需Shopify管理员API范围

根据您启用的工具，可能需要以下范围：

基本范畴

read_orders, write_orders
read_products, write_products
read_customers, write_customers
read_inventory, write_inventory
read_draft_orders, write_draft_orders
read_discounts, write_discounts
read_locations, write_locations
read_fulfillments, write_fulfillments

商业类别

read_gift_cards, write_gift_cards
read_returns, write_returns
read_checkouts, write_checkouts
read_payment_terms, write_payment_terms
read_order_edits, write_order_edits
read_companies, write_companies
read_cash_tracking, write_cash_tracking

营销类别

read_marketing_events, write_marketing_events
read_markets, write_markets
read_channels, write_channels
read_price_rules, write_price_rules
read_analytics
read_pixels, write_pixels
read_publications, write_publications

内容类别

read_metaobject_definitions, write_metaobject_definitions
read_metaobjects, write_metaobjects
read_themes, write_themes
read_files, write_files
read_pages, write_pages
read_translations, write_translations

高级类别

read_cart_transforms, write_cart_transforms
read_validations, write_validations
read_audit_events
read_customer_events
read_privacy_settings, write_privacy_settings

报告类别

read_reports, write_reports
read_apps, write_apps

自动化类别

read_inventory_shipments, write_inventory_shipments
read_inventory_transfers, write_inventory_transfers

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

TypeScript严格模式合规性
所有工具输入的Zod模式验证
所有GraphQL操作的错误处理
新工具的更新文档
正确分类 TOOL_CATEGORIES.md

支持

对于问题或疑问：

检查故障排除部分
验证您的Shopify API证书
确保您的访问令牌具有所需的范围
查看 Shopify管理GraphQL API文档
检查 TOOL_CATEGORIES.md 获取工具类别配置帮助

Shopify Graphql MCP

快速接入

详细介绍