Skip to main content
Glama
Hey Harper multi-store Shopify MCP server

Hey Harper multi-store Shopify MCP server

Hey Harper 多店铺 Shopify MCP 服务器

一个微型的远程 MCP 服务器,持有全部五个 Hey Harper 店铺的永久 Shopify Admin API 令牌,并通过一次连接拉取所有店铺中未发货/需要注意的候选订单——无需 switch-shop,也无需按店铺重新进行 OAuth 授权。这正是让每日“需要注意的订单”报告能够无人值守运行的原因。

为什么存在

官方的 Shopify 连接器一次只持有一个店铺,并且在每次切换店铺时都强制要求重新进行 OAuth 授权——这对于定时任务来说无法自动化。本服务器通过使用自定义应用 Admin API 令牌(永久有效,无需 OAuth)并直接查询所有店铺,完全绕开了这个问题。

Related MCP server: Shopify MCP

它暴露的工具

工具

功能

heyharper_list_stores

列出当前已配置的店铺(域名和令牌均已设置)。

heyharper_pull_store_orders

拉取单个店铺的未发货订单(store、since_days)。

heyharper_pull_all_stores

主要工具。 通过一次调用拉取所有店铺的未发货订单,并支持按店铺进行错误隔离。

它会返回规范化并丰富化后的每个订单(解析后的 released_hold_at、Everstox 标签标志、每行 oos),但刻意不判断“是否需要关注”——工作日延迟阈值、OOS 规则(仅限 EU/UK/BR/MX)以及 Everstox 排除项都保留在你的 Cowork 任务中,这样你就可以在不重新部署的情况下调整阈值和添加假日日历。


设置——逐步操作

1. 在每个店铺中创建自定义应用和令牌

在每个 Hey Harper 店铺后台(US、EU、UK、BR、MX)中:

  1. 设置 → 应用和销售渠道 → 开发应用 → 创建应用(例如命名为 cowork-unfulfilled-reader)。

  2. 配置 Admin API 作用域并启用(只读即可):

    • read_orders

    • read_all_orders (允许你查询超过 60 天的订单)

    • read_products

    • read_inventory

    • read_fulfillments

    • read_merchant_managed_fulfillment_orders

  3. 安装应用,然后在 API 凭据下显示 Admin API 访问令牌(shpat_…)。复制它。

  4. 记下店铺的 myshopify 域名(例如 hey-harper-shop-uk.myshopify.com)。

你最终会得到五对 (domain, token)。切勿提交这些信息或将其粘贴到聊天中——它们会直接进入第 3 步中主机的密钥存储。

2. 部署服务器

该仓库附带了一个 Dockerfile,因此任何容器主机都可以使用(Render、Railway、Fly.io、VPS)。它必须具有正常的互联网访问权限和一个公共 HTTPS URL。

Render(示例,最简单):

  • 新建 → Web Service → 连接此仓库(或“从 Dockerfile 部署”)。

  • Render 会自动检测 Dockerfile。无需构建/启动命令。

  • 它会自动提供 HTTPS 和公共 URL。

Fly.io / Railway: 以同样的方式将它们指向 Dockerfile。

本地测试:

npm install
npm run build
MCP_AUTH_TOKEN=$(openssl rand -hex 32) HH_UK_DOMAIN=hey-harper-shop-uk.myshopify.com HH_UK_TOKEN=shpat_xxx npm start
# health check:
curl localhost:3000/health

3. 在主机上设置环境密钥

复制 .env.example 作为参考,并在主机的环境/密钥 UI 中设置以下内容:

  • MCP_AUTH_TOKEN — 一个长的随机字符串(openssl rand -hex 32)。请务必设置——它是保护你端点的 Bearer 令牌。

  • HH_US_DOMAIN / HH_US_TOKEN、HH_EU_*、HH_UK_*、HH_BR_*、HH_MX_* — 第 1 步中的配对。

只有当店铺的域名和令牌都设置好后,该店铺才会生效,因此你可以从 UK 开始,并在生成令牌后添加其余店铺。

4. 将其作为自定义连接器添加到 Claude

在 claude.ai → 设置 → 连接器 → 添加自定义连接器中:

  • URL: https://<your-host>/mcp

  • 认证: 提供 Bearer 令牌(MCP_AUTH_TOKEN),以便请求发送 Authorization: Bearer <token>。

如果你的方案中连接器 UI 无法附加静态请求头,另一种方法是将 MCP_PATH 设置为一个不可猜测的路径(例如 /mcp/9f3c…)并将其用作 URL——这样秘密路径就充当了凭据。在支持的情况下,优先使用 Bearer 令牌。

连接后,heyharper_list_stores、heyharper_pull_store_orders 和 heyharper_pull_all_stores 会作为工具出现。

5. 配置每日报告

将你每天上午 9 点的 Cowork 任务指向 heyharper_pull_all_stores,然后应用分类逻辑(根据交接规范保留在任务中):

clock    = releasedHoldAt if hasReleasedHold else processedAt
late     = business_days_since(clock) >= 2      (weekends excluded, warehouse TZ)
shop_oos = anyLineOos                            (only where storeAppliesOos)
excluded = hasOosEverstox OR (hasHoldEverstox AND NOT hasReleasedHold)
           OR (hasSetOnHold AND NOT hasReleasedHold)
needs_attention = (late OR shop_oos) AND NOT excluded

将汇总发布到 #daily-unfulfilled。


安全说明

  • 令牌仅存在于主机的环境/密钥中——绝不会出现在仓库中(.env 已被 gitignore 忽略)。

  • 在公开 URL 之前,请务必设置 MCP_AUTH_TOKEN;如果缺少该变量,服务器会记录警告。

  • 所有工具都是只读的(仅限 read_* 作用域)——服务器无法修改你的店铺。

环境变量

变量

必需

默认值

说明

MCP_AUTH_TOKEN

推荐

—

端点的 Bearer 令牌。如果未设置,端点将开放。

MCP_PATH

否

/mcp

端点路径。

PORT

否

3000

通常由主机设置。

SHOPIFY_API_VERSION

否

2024-10

Admin API 版本。

HH_<KEY>_DOMAIN

按店铺

—

KEY ∈ US、EU、UK、BR、MX。

HH_<KEY>_TOKEN

按店铺

—

shpat_… Admin API 访问令牌。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that exposes the full Shopify Admin GraphQL API through 6 universal tools, with multi-store support and mutation rejection at the parser level for safety.
      6
      30 PyPI
      1
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      MCP server for Shopify Admin API. Enables product, order, customer, and inventory management via natural language.
      14
      7 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Hosted MCP server connecting Shopify, Klaviyo, GA4, Meta Ads, Google Ads, Xero, Gorgias and 20+ e-commerce data sources so AI assistants can answer merchant questions that span every source at once.
      -