magento-mcp

MCP-сервер, предоставляющий доступ к магазину Magento 2 для ИИ-ассистентов через:

• 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 плюс учётные данные OAuth 1.0a из Magento Integration (System → Extensions → Integrations → Add New Integration): MAGENTO_CONSUMER_KEY, MAGENTO_CONSUMER_SECRET, MAGENTO_ACCESS_TOKEN, MAGENTO_ACCESS_TOKEN_SECRET. Выдайте Integration только те ресурсы API, которые реально нужны серверу, — Magento показывает эти четыре значения только один раз, при активации. Это также позволяет обойти ограничение 2FA, которое блокирует вход по паролю администратора, и является подходом с минимальными привилегиями.

   • MAGENTO_DB_* — обязательно должен указывать на пользователя MySQL с правами только на чтение (SELECT):

     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 — проверка подключений к REST, GraphQL и БД с использованием значений из .env перед подключением сервера к ассистенту. См. раздел «Локальная разработка с самоподписанными сертификатами», если возникают ошибки 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": "..."
         }
       }
     }
   }

   Поля MAGENTO_DB_SSH_* нужны только при подключении к БД через SSH-туннель — если они не нужны, просто не указывайте их (а не оставляйте пустыми), чтобы подключение шло напрямую. См. раздел «Подключение к удалённой/изолированной БД» ниже.

Разработка

• npm run dev — запуск напрямую из исходников через tsx

• npm run typecheck

• npm test — модульные тесты (src/db/guard.test.ts покрывает проверки безопасности SQL-запросов)

• npm run test:connections — проверка подключений к REST/GraphQL/БД с использованием значений из .env (не заменяет npm test)

• npx @modelcontextprotocol/inspector node dist/index.js — интерактивный просмотр и вызов инструментов

Локальная разработка с самоподписанными сертификатами (mkcert, Warden и т.п.)

fetch в Node.js использует собственный список доверенных центров сертификации, отдельный от системного хранилища — поэтому даже если curl и ваш браузер доверяют локально выпущенному сертификату mkcert, Node.js отклонит его с ошибкой UNABLE_TO_VERIFY_LEAF_SIGNATURE. Укажите Node.js тот же корневой CA:

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

или задайте переменную NODE_EXTRA_CA_CERTS в окружении, в котором запускается MCP-клиент (например, в блоке env в claude_desktop_config.json). Также проверьте, что MAGENTO_BASE_URL точно соответствует имени хоста, указанному в сертификате (ошибка ERR_TLS_CERT_ALTNAME_INVALID означает, что не соответствует) — в локальных установках Magento часто настроено несколько хостов *.local/*.example.com, и сертификат покрывает только один из них.

Подключение к удалённой/изолированной БД (SSH-туннель)

MAGENTO_DB_HOST/PORT не обязаны указывать на ту же машину, где работает сервер, — mysql2 просто подключается по TCP. Но ни в коем случае не открывайте порт MySQL в открытый интернет. Если БД недоступна напрямую через частную сеть/VPN, задайте MAGENTO_DB_SSH_* в .env (полный список полей — в .env.example), чтобы подключение к БД шло через SSH-туннель: сервер сам устанавливает SSH-соединение (через пакет ssh2, а не внешний процесс ssh) и пробрасывает локальный порт на MAGENTO_DB_HOST/PORT так, как они разрешаются на стороне SSH-хоста. Предпочтительнее использовать закрытый ключ (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), а не замена им.

• Таймаут запроса и максимальное количество строк настраиваются через MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS в .env.