Skip to main content
Glama
magento-mcp

magento-mcp

by FahadEjaz

magento-mcp

Magento 2 스토어를 AI 어시스턴트에 노출하는 MCP 서버로, 다음을 통해 제공됩니다:

  • REST Admin API — 카탈로그, 주문, 고객, CMS, 재고, 프로모션, 스토어 구성(쓰기 도구는 confirm: true 필요), Magento Integration에 대한 OAuth 1.0a로 인증

  • 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. Integration에 이 서버가 실제로 필요로 하는 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, DB 연결을 정상적으로 확인합니다. 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_* 필드는 DB 연결을 SSH로 터널링할 때만 필요합니다 — 직접 연결하려면 이전처럼 해당 필드를 완전히 생략하세요(비워 두는 것이 아니라). 아래 "원격/방화벽 DB에 연결"을 참조하세요.

개발

  • npm run dev — tsx를 통해 TS 소스에서 직접 실행

  • npm run typecheck

  • npm test — 단위 테스트 (src/db/guard.test.ts는 SQL 안전 가드레일을 다룹니다)

  • npm run test:connections — .env에 대한 REST/GraphQL/DB 연결 가능성의 라이브 스모크 테스트 (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 호스트 이름이 구성되어 있고 일치하는 인증서가 하나만 있는 경우가 많습니다.

원격/방화벽 DB에 연결 (SSH 터널)

MAGENTO_DB_HOST/PORT는 이 서버와 같은 머신에 있을 필요가 없습니다 — mysql2는 TCP로 연결하기만 하면 됩니다. 그러나 이를 위해 MySQL 포트를 공개 인터넷에 노출하지 마세요. DB가 이미 사설 네트워크/VPN을 통해 연결 가능하지 않다면 .env에 MAGENTO_DB_SSH_*를 설정하여(전체 필드 목록은 .env.example 참조) DB 연결을 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 참조. 이는 DB 사용자의 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
      30 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
      -