Medusa

medusa-mcp

🇨🇿 Česky

适用于 Medusa v2 Admin API 的 MCP 服务。它让 Claude、ChatGPT 或任何 MCP 客户端都能管理 Medusa 商店：订单、付款和退款、退货、订单编辑、草稿订单、产品和目录、库存、客户、促销和价格表——还可在聊天中直接通过交互式仪表板查看销售、客户和补货分析。

• 55 个工具，用于日常商店管理；medusa_request 可用于其他任何 Admin API 端点
• 交互式视图（MCP Apps）——销售仪表板和补货计划工具可直接在 Claude 和 ChatGPT 中呈现
• 提示词——可直接使用的工作流（商店简报、履约、退货、补货、月度报告……），可作为斜杠命令调用
• 资源——可作为附件上下文的订单、产品和客户，并支持自动补全
• 防护措施——批量更改前提供预览（试运行），破坏性操作需经确认对话框，每项更改都会记录在审计日志中

它支持两种运行模式：

• stdio——在本地运行，适用于 Claude Desktop、Claude Code 和其他 MCP 客户端
• Streamable HTTP + OAuth 2.1——作为远程连接器，适用于 Claude（网页、桌面、移动端）和 ChatGPT

它已列入 MCP Registry，名称为 io.github.trhonpavel/medusa-mcp；此外还提供带技能的 Claude Code / Cowork 插件，以及可一键安装的 Claude Desktop 扩展（.mcpb）。

工具

读取和分析

工具	功能
get_store_info	地区和货币、销售渠道、库存地点、配送选项和配置、退货和退款原因
list_orders / get_order	按全文、日期范围、客户或状态查询订单；按 ID 或订单号（1042）查看完整详情，包括付款、退款、折扣码和退货
list_customers / get_customer	客户（也可按分组或电子邮件查询）、订单历史记录、消费总额
list_customer_groups	客户分组
list_products / get_product	按状态、系列、类别或标签查询产品；查看变体、选项、价格、图片、库存项目（按 ID 或句柄查询）
list_catalog	类别（树状结构）、系列、标签、产品类型
list_inventory	各地点的库存；使用 low_stock_threshold 查找即将缺货的商品
list_promotions / list_price_lists	含条件、使用情况和有效期的折扣码；促销和客户分组价格表
sales_report	收入、退款后的净收入、平均订单金额（AOV）、商品数量、客户数——与上一时段或去年同期比较；按日／周／月统计、热门产品和变体、国家／地区、折扣码、销售渠道 · 交互式仪表板
customer_report	新客户与回头客、重复购买率、重要客户、值得挽回的流失客户
inventory_forecast	销售速度与库存对比：库存可覆盖天数、缺货／立即补货／即将补货、建议订购数量、滞销商品 · 交互式补货计划工具

写入（设置 MEDUSA_READ_ONLY=true 时不会注册）

区域	工具
履约	create_fulfillment（默认处理所有剩余商品，使用唯一的库存地点）、create_shipment（跟踪号码）、mark_delivered、cancel_fulfillment
订单	update_order（电子邮件、地址、元数据）、edit_order（添加、更改或移除商品——先预览新总额）、complete_order、cancel_order
付款	mark_order_paid（银行转账、货到付款——也适用于已转换的草稿订单）、capture_payment、refund_payment（检查可退款金额）
退货	create_return（默认包括所有已发货商品）、receive_return（将商品放回库存）
草稿订单	create_draft_order（按变体或 SKU 添加商品、自定义价格、运费）、convert_draft_order
商品	create_product（简单商品或带选项和变体的商品、初始库存；默认使用销售渠道和配送配置文件）、update_product、add_product_images（从 URL 添加图片，并复制到商店的存储空间）、delete_product
变体	create_variant（自动添加新的选项值）、update_variant、delete_variant、set_variant_price（保留所有其他价格）
目录	save_category、delete_category、save_collection、delete_collection（创建或更新、添加/移除商品）
库存	set_stock_level（设置绝对值或使用 adjust_by: +10 调整；将商品添加到新的地点）
客户	save_customer（创建/更新、地址、分组）、save_customer_group、delete_customer_group
促销	create_promotion（百分比折扣、固定金额折扣或免运费；适用于商品、分类、集合、客户分组；可设定日期和使用次数上限）、update_promotion、delete_promotion
价格列表	save_price_list（销售价格和 B2B 价格，按变体或 SKU 更新价格）、delete_price_list
批量	bulk_update_prices（按百分比、金额或固定价格更新，并可设置类似 199 或 19.99 的价格尾数）、bulk_set_stock（收货、盘点）、bulk_update_products（发布、分类、标签、集合、销售渠道）——全部先通过 dry_run 预览

通用

工具	功能
medusa_request	任意 Admin API 端点（/admin/ 下的 GET、POST、DELETE），用于没有专用工具的操作——预留、换货、税率……只读模式仅允许 GET；始终禁止写入 api-keys、users 和 invites。使用 MEDUSA_RAW_API=false 将其关闭。

金额以主要货币单位计（Medusa v2 不存储次要单位）。简单日期（2026-09-01）按照 REPORT_TIMEZONE 解释（默认值为 UTC）。大型报告会发送 MCP 进度通知。

更少的工具，占用更少的上下文：MEDUSA_TOOLSETS=orders,reports 只注册这些分组（orders、customers、products、catalog、inventory、pricing、promotions、reports、bulk、raw；get_store_info 始终启用）。

工具之外

交互式视图（MCP Apps）。 sales_report 和 inventory_forecast 配有 HTML 视图，支持 MCP Apps 的客户端——Claude、ChatGPT、VS Code、Goose——可直接内嵌渲染：销售报告视图包含带环比变化的 KPI 磁贴、收入图表、热销产品、折扣码和国家；库存预测视图包含可排序的补货表格、状态筛选器、可调整的交付周期，以及一个用于请求助手起草采购订单的按钮。这些视图会采用客户端的主题和语言（捷克语或英语），通过调用工具本身切换周期，而且不会自行发起网络请求。其他客户端会以文本形式获取相同数据。

提示词。 store_briefing、fulfill_orders、restock_plan、handle_return、customer_overview、monthly_report 和 plan_promotion——每个提示词都会引导助手完成整个工作流，并在更改任何内容前征求确认。参数支持自动补全（订单号、客户电子邮件、月份）。

资源。 medusa://store、medusa://orders/{order}、medusa://products/{handle} 和 medusa://customers/{email}——将订单或产品附加到对话中（例如，在 Claude Code 中使用 @）；系统会列出最近的订单，并自动补全每个模板。

确认。 对于破坏性操作——取消、退款、收款、删除、批量更改，以及通过 medusa_request 执行的写入操作——如果客户端支持（Claude Code），系统会通过 MCP elicitation 直接向用户确认，并提供通俗易懂的摘要（“要向订单 1042 的客户退还 249 CZK 吗？”）。拒绝确认不会产生任何更改。将 MEDUSA_CONFIRM_DESTRUCTIVE=false 可关闭此功能。无状态远程连接器无法请求确认，因此会采用客户端自身的工具审批机制。

1. 创建 Medusa API 密钥

在 Medusa Admin 中，前往 Settings → Developer → Secret API Keys → Create。此密钥（sk_…）具有创建者用户的权限，因此建议使用可单独撤销权限的专用管理员用户。

2. 本地使用（stdio）

Claude Code / Cowork 插件

claude plugin marketplace add trhonpavel/medusa-mcp
claude plugin install medusa@medusa-mcp

启用插件时，Claude Code 会询问后端 URL 和 API 密钥（密钥会保存到系统密钥链中）。写入工具默认关闭，需在 /config 中关闭 Read-only 才能启用。除了服务端提示词，插件还提供两个技能：

• store-briefing – 汇总与上一周期相比的销售情况、等待发货的已付款订单，以及需要补货的商品
• fulfill-orders – 完成已付款订单的履行并添加跟踪编号，需先确认订单列表

Claude Desktop 扩展

从最新版本下载 medusa-mcp-<version>.mcpb 并打开，或将其拖到 Settings → Extensions。Claude Desktop 会询问相同的设置，并使用随附的 Node.js 运行服务。也可以使用 npm run build:mcpb 自行构建。

手动配置

Claude Desktop – claude_desktop_config.json：

{
  "mcpServers": {
    "medusa": {
      "command": "npx",
      "args": ["-y", "medusa-mcp", "stdio"],
      "env": {
        "MEDUSA_BACKEND_URL": "https://api.example.com",
        "MEDUSA_API_KEY": "sk_...",
        "MEDUSA_READ_ONLY": "true"
      }
    }
  }
}

Claude Code：

claude mcp add medusa \
  -e MEDUSA_BACKEND_URL=https://api.example.com -e MEDUSA_API_KEY=sk_... \
  -- npx -y medusa-mcp stdio

3. 远程连接器（HTTP + OAuth）

docker run -d --name medusa-mcp -p 127.0.0.1:3000:3000 -v medusa-mcp-data:/data \
  -e MEDUSA_BACKEND_URL=https://api.example.com \
  -e MEDUSA_API_KEY=sk_... \
  -e PUBLIC_URL=https://mcp.example.com \
  -e OWNER_PASSWORD="$(openssl rand -base64 24)" \
  ghcr.io/trhonpavel/medusa-mcp:latest

或者克隆仓库，将 .env.example 复制为 .env，然后运行 docker compose up -d --build。

服务监听 127.0.0.1:3000；通过带 TLS 的反向代理将其公开。Claude 从 Anthropic 的服务器连接远程连接器，因此端点必须可通过 HTTPS 公开访问。Caddy 示例：

mcp.example.com {
    reverse_proxy 127.0.0.1:3000
}

然后在 Claude 中添加自定义连接器，URL 为 https://mcp.example.com/mcp。Claude 会自行注册（Dynamic Client Registration），打开授权页面；输入 OWNER_PASSWORD 并点击 Allow。

ChatGPT

在 ChatGPT 设置中开启 developer mode，然后创建一个应用（连接器），设置 MCP 服务 URL https://mcp.example.com/mcp 并使用 OAuth 身份验证。ChatGPT 会以相同方式自行注册，并重定向到 chatgpt.com；该域名已包含在默认的 ALLOWED_REDIRECT_HOSTS 中。服务会返回 RFC 9207 iss 参数，因此 ChatGPT 会使用其稳定的回调 URL。

Claude Code

Claude Code 可以使用相同的 OAuth 流程，也可以通过设置 MCP_STATIC_TOKEN 使用静态令牌：

claude mcp add --transport http medusa https://mcp.example.com/mcp \
  --header "Authorization: Bearer <MCP_STATIC_TOKEN>"

配置

变量	必需	默认值	描述
MEDUSA_BACKEND_URL	是		Medusa 后端 URL
MEDUSA_API_KEY	是		秘密 API 密钥（sk_…）
MEDUSA_READ_ONLY		false	仅注册读取和报告工具
MEDUSA_RAW_API		true	注册通用的 medusa_request 工具（只读模式下仅支持 GET）
MEDUSA_TOOLSETS		all	要注册的工具组，以逗号分隔，例如 orders,reports
MEDUSA_CONFIRM_DESTRUCTIVE		true	在执行破坏性操作前通过 MCP elicitation 请求确认（支持此功能的客户端）
AUDIT_LOG			接收每次写入工具调用的文件，每次调用记录为一行 JSON（它们也始终会输出到 stderr）
REPORT_TIMEZONE		UTC	日期筛选和报告分组使用的 IANA 时区
MEDUSA_TIMEOUT_MS		20000	Medusa 请求的超时时间
PUBLIC_URL	HTTP		此服务的公开 HTTPS 源站（不含 /mcp）
OWNER_PASSWORD	HTTP		同意页面所需的密码
MCP_STATIC_TOKEN			可选的静态 bearer 令牌
ALLOWED_REDIRECT_HOSTS		claude.ai,claude.com,chatgpt.com,localhost,127.0.0.1	OAuth 客户端可用作重定向目标的主机
TRUST_PROXY		1	Express trust proxy——前置代理的数量
PORT / HOST		3000 / 0.0.0.0	监听地址
DATA_DIR		./data	存储 OAuth 客户端和令牌哈希的位置
ACCESS_TOKEN_TTL / REFRESH_TOKEN_TTL		3600 / 2592000	令牌有效期，单位为秒

端点

路径	用途
POST /mcp	通过 Streamable HTTP 提供 MCP（无状态），需要 bearer 令牌
/.well-known/oauth-protected-resource/mcp	RFC 9728 受保护资源元数据
/.well-known/oauth-authorization-server	RFC 8414 授权服务器元数据
/register、/authorize、/token、/revoke	OAuth 2.1（DCR、PKCE S256）
POST /oauth/login	同意表单（限流：每个 IP 每 15 分钟最多尝试 10 次）
GET /healthz	健康检查

安全模型

• Medusa API 密钥不会离开服务端。客户端会获得各自的短期令牌（1 小时访问有效期、30 天刷新有效期，并轮换刷新令牌）。
• 令牌仅以 SHA-256 哈希形式存储在 DATA_DIR/oauth-state.json 中（权限模式为 600）。删除该文件即可让所有客户端退出登录。
• 动态客户端注册仅接受 ALLOWED_REDIRECT_HOSTS 上的重定向 URI，因此任意应用都无法注册自己的回调地址来窃取令牌。
• 授权码只能使用一次，有效期为 5 分钟，并且必须使用 PKCE S256。
• 同意页面会发送 Content-Security-Policy: default-src 'none' 和 X-Frame-Options: DENY，并以恒定时间比较密码。
• 写入工具不会标记为 readOnlyHint；取消、删除或转移资金的工具会带有 destructiveHint，因此 Claude 等客户端会在运行前请求批准。
• medusa_request 只能访问 /admin/… 路径，绝不会写入 api-keys、users 或 invites（因此提示词注入无法生成新凭据）；还可通过 MEDUSA_RAW_API=false 将其禁用。
• 每次写入工具调用都会以 [audit] {…} 的格式记录到 stderr（docker logs）——包括时间、工具、OAuth 客户端（例如“Claude”）、结果和参数；设置 AUDIT_LOG 后也会记录到该文件。
• 当客户端支持 MCP 询问时，破坏性操作会通过 MCP 询问请求确认；批量工具和 edit_order 默认会先预览，只有在调用时传入 dry_run: false 才会进行更改。
• add_product_images 只会从公开的 http(s) 地址下载内容：私有、环回和链路本地目标均会被拒绝，重定向后也一样，因此无法利用该服务访问其自身网络。
• 交互式视图是独立的 HTML（不含外部脚本或请求），并由客户端在沙盒 iframe 中渲染。
• 将 TRUST_PROXY 设置为服务端前方反向代理的数量，否则限流只能识别代理的 IP。

如需报告漏洞，请参阅 SECURITY.md。

开发

npm ci
npm run build   # TypeScript + the MCP Apps views (dist/apps/*.html with the ext-apps runtime inlined)
npm test        # build + tests against a mock Medusa (tools, prompts, resources, views and the full OAuth flow)
npm run smoke   # read-only check against a real Medusa – prints response shapes only, no data
npm run dev     # HTTP mode via tsx

npm run smoke 需要 MEDUSA_BACKEND_URL 和 MEDUSA_API_KEY。其输出仅包含键和类型，可安全地粘贴到问题帖中。

许可证

MIT