Magento MCP Server

Magento MCP服务器

一 MCP（模型上下文协议） 服务器 Adobe Commerce/Magento 2 行政。将人工智能助手（如Claude、Windsurf、Cursor和其他MCP兼容客户端）连接到您的Magento实例，以进行业务级操作——目录管理、促销、CMS、诊断等。

特性

• 30+工具 通过标准MCP协议进行Magento管理
• OAuth 1.0（HMAC-SHA256） 集成身份验证--无2FA提示
• 两阶段提交 对于批量操作（准备→ 审查→ 承诺）
• 内置护栏 --批量上限、价格变动警告、确认要求
• 多店铺感知 --网站、商店和商店视图的明确范围处理
• 审核日志记录 --每个操作都记录了时间戳、用户和参数

可用工具

授权和范围

• auth.login / auth.logout / auth.whoami --会话管理
• scope.list_websites_stores / scope.set_default --多店铺范围

目录

• catalog.search_products --使用过滤器、分页、字段投影进行搜索
• catalog.get_product --按SKU列出的完整产品详细信息
• catalog.prepare_bulk_update / catalog.commit_bulk_update --两阶段批量产品更新

定价

• pricing.prepare_bulk_price_update / pricing.commit_bulk_price_update --安全批量价格变化与阈值警告

促销

• promotions.search_rules / promotions.get_rule --查找并检查购物车价格规则
• promotions.prepare_cart_price_rule_create / promotions.commit_cart_price_rule_create --安全地创建规则
• promotions.update_rule / promotions.enable_rule / promotions.disable_rule
• promotions.generate_coupons / promotions.export_coupons

内容管理系统

• cms.search_pages / cms.get_page --查找和阅读CMS页面
• cms.prepare_bulk_update_pages / cms.commit_bulk_update_pages
• cms.search_blocks / cms.get_block
• cms.prepare_bulk_update_blocks / cms.commit_bulk_update_blocks

搜索引擎优化

• seo.prepare_bulk_update_url_keys / seo.commit_bulk_update_url_keys --URL键随冲突检测而更改
• seo.bulk_update_meta --批量元标题/描述/关键字更新
• seo.report_redirect_chains --查找重定向链问题

诊断

• diagnostics.product_display_check --为什么我的产品没有显示出来？
• diagnostics.indexer_status_report --索引器健康检查
• diagnostics.inventory_salable_report --MSI库存/可销售数量

缓存

• cache.purge_by_url / cache.purge_product / cache.purge_category --目标缓存失效（快速或回退）

快速开始

先决条件

• Node.js 18+
• Magento 2/Adobe Commerce实例
• 一 集成 使用适当的API权限在Magento中配置

安装

git clone https://github.com/thomastx05/magento-mcp.git
cd magento-mcp
npm install
npm run build

Magento集成设置

1. 在Magento管理中，转到 系统>集成>添加新集成
2. 为其命名（例如，“MCP服务器”）
3. 在...之下 API，选择要公开的资源
4. 保存和 激活 整合
5. 复制四个OAuth凭据：

- 消费者密钥 - 消费者秘密 - 访问令牌 - 访问令牌密钥

MCP客户端配置

添加到您的MCP客户端配置中（例如。， mcp_config.json 对于Windsurf， claude_desktop_config.json 克劳德桌面版）：

{
  "mcpServers": {
    "magento-mcp": {
      "command": "node",
      "args": ["C:/path/to/magento-mcp/dist/index.js"],
      "env": {
        "MAGENTO_BASE_URL": "https://your-magento-instance.com",
        "MAGENTO_OAUTH_CONSUMER_KEY": "your_consumer_key",
        "MAGENTO_OAUTH_CONSUMER_SECRET": "your_consumer_secret",
        "MAGENTO_OAUTH_TOKEN": "your_access_token",
        "MAGENTO_OAUTH_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

替代方案：用户名/密码验证

如果您更喜欢管理员令牌身份验证而不是OAuth（如果启用，则需要处理2FA）：

{
  "env": {
    "MAGENTO_BASE_URL": "https://your-magento-instance.com",
    "MAGENTO_ADMIN_USERNAME": "your_admin_user",
    "MAGENTO_ADMIN_PASSWORD": "your_admin_password"
  }
}

用法

配置后，调用 auth.login 首先建立会话，然后使用任何工具：

> auth.login
Login successful (OAuth 1.0 integration)

> catalog.search_products { filters: { name: { value: "%eye drops%", condition: "like" } } }
Found 12 products...

> diagnostics.inventory_salable_report { sku: "PROD-001" }
Qty: 3,805 | In Stock: Yes | Backorders: Enabled

建筑

src/
  index.ts              # MCP server entry point (McpServer + StdioServerTransport)
  config/index.ts       # Configuration & guardrail defaults
  actions/              # Tool handlers (one file per domain)
    auth.ts
    catalog.ts
    pricing.ts
    promotions.ts
    cms.ts
    seo.ts
    diagnostics.ts
    cache.ts
    scope.ts
  client/
    magentoRest.ts      # REST client with OAuth 1.0 signing
    fastlyClient.ts     # Optional Fastly CDN integration
  session/
    sessionStore.ts     # In-memory session & OAuth credential storage
    planStore.ts        # Two-phase commit plan storage
    idempotencyLedger.ts
  validation/
    schemas.ts          # Zod input schemas for all tools
    guardrails.ts       # Safety checks (bulk caps, price thresholds, confirmations)
  protocol/
    types.ts            # TypeScript interfaces
  audit/
    auditLogger.ts      # Action audit trail (JSONL)

安全

• 磁盘上没有存储凭据 --OAuth令牌通过环境变量传递，仅保存在内存中
• Magento ACL已强制执行 -集成的API权限控制服务器可以执行的操作
• 顶部护栏 --批量操作上限、价格变化阈值和确认要求提供了深度防御
• 两阶段提交 --破坏性批量操作需要明确的审查和确认
• 审计跟踪 --每个操作都会记录时间戳、用户、参数和结果

配置

护栏和限制可在中配置 src/config/index.ts:

可选：快速CDN集成

对于通过Fastly进行的目标缓存清除，请添加以下环境变量：

{
  "env": {
    "FASTLY_SERVICE_ID": "your_service_id",
    "FASTLY_API_TOKEN": "your_api_token"
  }
}

许可证

麻省理工学院