Skip to main content
Glama
magento-mcp

magento-mcp

by FahadEjaz

magento-mcp

通过以下方式向 AI 助手公开 Magento 2 商店的 MCP 服务器:

  • REST Admin API — 目录、订单、客户、CMS、库存、促销、商店配置(写入工具需要 confirm: true),通过 OAuth 1.0a 针对 Magento Integration 进行身份验证

  • GraphQL — 面向商店前端的目录搜索、产品详情、分类树

  • 直接只读 SQL — 一个 run_readonly_sql 工具,以及针对实时 Magento 数据库的预构建洞察查询,可选通过 SSH 隧道访问

工具

工具

领域

说明

search_products、get_product、list_categories

目录

只读

update_product、delete_product

目录

破坏性操作,需要 confirm: true

search_orders、get_order

订单

只读

cancel_order、refund_order

订单

破坏性操作,需要 confirm: true

search_customers、get_customer

客户

只读

update_customer、delete_customer

客户

破坏性操作,需要 confirm: true

list_cms_pages、get_cms_page、list_cms_blocks

CMS

只读

get_stock_item、list_source_items

库存

只读

update_stock_item

库存

破坏性操作,需要 confirm: true

list_cart_price_rules、get_coupon_by_code

促销

只读

get_store_config、list_store_views

商店配置

只读

set_config_value

商店配置

破坏性操作,需要 confirm: true

search_catalog、get_product_details、get_category_tree

GraphQL 目录

只读,面向商店前端的查询

run_readonly_sql

数据库

仅限单个 SELECT — 参见安全说明

top_selling_products、low_stock_items、abandoned_carts

数据库

预构建的只读洞察查询

此外还暴露了一个 MCP 资源:magento://store/config(商店配置 — 货币、区域设置、商店视图、基础 URL)。

Related MCP server: Shopify MCP

设置

  1. npm install

  2. 将 .env.example 复制为 .env,并填写:

    • MAGENTO_BASE_URL 以及来自 Magento Integration(系统 → 扩展 → 集成 → 添加新集成)的 OAuth 1.0a 凭据:MAGENTO_CONSUMER_KEY、MAGENTO_CONSUMER_SECRET、MAGENTO_ACCESS_TOKEN、MAGENTO_ACCESS_TOKEN_SECRET。仅授予该集成此服务器实际需要的 API 资源 — Magento 在激活时仅显示一次这四个值。这样可以避开阻止管理员密码身份验证的 2FA 限制,同时也是最低权限的做法。

    • MAGENTO_DB_* — 必须指向一个仅具有 SELECT 权限的 MySQL 用户:

      CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'change_me';
      GRANT SELECT ON magento_db.* TO 'mcp_readonly'@'%';
      FLUSH PRIVILEGES;

      在任何情况下都不要授予该用户 INSERT/UPDATE/DELETE/DDL 权限 — 应用程序级别的查询防护(src/db/guard.ts)是纵深防御,而不是安全边界。

  3. npm run build

  4. npm run test:connections — 在将服务器接入助手之前,根据 .env 中的值对 REST、GraphQL 和数据库连接进行健康检查。如果 TLS 检查失败,请参见下面的使用自签名证书进行本地开发。

  5. 在 Claude Desktop/Code 中注册,例如在 claude_desktop_config.json 中:

    {
      "mcpServers": {
        "magento": {
          "command": "node",
          "args": ["/var/www/html/magentoMCP/dist/index.js"],
          "env": {
            "MAGENTO_BASE_URL": "...",
            "MAGENTO_CONSUMER_KEY": "...",
            "MAGENTO_CONSUMER_SECRET": "...",
            "MAGENTO_ACCESS_TOKEN": "...",
            "MAGENTO_ACCESS_TOKEN_SECRET": "...",
            "MAGENTO_DB_HOST": "...",
            "MAGENTO_DB_NAME": "...",
            "MAGENTO_DB_READONLY_USER": "...",
            "MAGENTO_DB_READONLY_PASSWORD": "...",
            "MAGENTO_DB_SSH_HOST": "...",
            "MAGENTO_DB_SSH_USER": "...",
            "MAGENTO_DB_SSH_PRIVATE_KEY_PATH": "..."
          }
        }
      }
    }

    仅当需要通过 SSH 隧道连接数据库时才需要 MAGENTO_DB_SSH_* 字段 — 如果要直接连接,请完全省略它们(而不是留空),如前所述。参见下面的"访问远程/防火墙后的数据库"。

开发

  • npm run dev — 通过 tsx 直接从 TS 源码运行

  • npm run typecheck

  • npm test — 单元测试(src/db/guard.test.ts 覆盖 SQL 安全防护)

  • npm run test:connections — 针对 .env 的 REST/GraphQL/数据库连通性实时测试(不能替代 npm test)

  • npx @modelcontextprotocol/inspector node dist/index.js — 交互式列出/调用工具

使用自签名证书进行本地开发(mkcert、Warden 等)

Node 的 fetch 使用其自带的 CA 证书列表,与系统的信任库是分开的 — 因此,即使 curl 和你的浏览器信任本地签发的 mkcert 证书,Node 也会以 UNABLE_TO_VERIFY_LEAF_SIGNATURE 拒绝它。让 Node 指向相同的根 CA:

NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem npm run dev

或者在 MCP 客户端启动服务器的环境中设置 NODE_EXTRA_CA_CERTS(例如 claude_desktop_config.json 中的 env 块)。另外,请仔细检查 MAGENTO_BASE_URL 是否确实与证书覆盖的主机名匹配(ERR_TLS_CERT_ALTNAME_INVALID 表示不匹配)— 本地 Magento 环境通常配置了多个 *.local/*.example.com 主机名,但只有一个有匹配的证书。

访问远程/防火墙后的数据库(SSH 隧道)

MAGENTO_DB_HOST/PORT 不必与此服务器位于同一台机器上 — mysql2 只是通过 TCP 连接。但绝不要为了使其工作而将 MySQL 的端口暴露到公网。如果数据库尚不能通过私有网络/VPN 访问,请在 .env 中设置 MAGENTO_DB_SSH_*(完整字段列表参见 .env.example),以通过 SSH 隧道连接数据库 — 此服务器自行建立 SSH 连接(通过 ssh2 包,而不是调用外部的 ssh 进程),并将本地端口转发到 SSH 主机侧解析出的 MAGENTO_DB_HOST/PORT。优先使用私钥(MAGENTO_DB_SSH_PRIVATE_KEY_PATH)而不是密码。如果希望直接连接,请将 MAGENTO_DB_SSH_HOST 留空,如前所述 — 隧道是可选功能,仅当该变量存在时才会启用。

安全说明

  • 每个破坏性 REST 工具(update_product、delete_product、cancel_order、refund_order、update_customer、delete_customer、update_stock_item、set_config_value)都会预览操作,并且除非使用 confirm: true 调用,否则不会执行。

  • run_readonly_sql 仅接受单个 SELECT 语句,拒绝 DML/DDL 关键字和敏感表(admin_user 等),并强制注入/限制 LIMIT — 参见 src/db/guard.ts。这是在数据库用户仅具有 SELECT 权限之上的额外保护,而不是替代它。

  • 查询超时和行数上限可通过 .env 中的 MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS 配置。

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
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server for MySQL database operations, providing secure HTTP endpoints for read-only queries, performance analysis, and server monitoring.
      22
      MIT
    • 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
      25 PyPI
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Security-focused MCP server for Shopify Admin GraphQL with read-only queries by default and mutations requiring preview and one-time confirmation. It manages short-lived tokens internally and enforces strict scope and approval controls.
      4
      11 npm
      -