magento-mcp

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

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

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

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

工具

此外还暴露了一个 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 配置。