magento-mcp

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

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

• 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. 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로 구성할 수 있습니다.