우리가 현재 진행하는 모든 WooCommerce 통합 프로젝트는 고객으로부터 동일한 질문을 받으며 끝납니다: "AI가 저를 대신해 스토어를 확인해 줄 수 있나요?" 지난달 매출은 얼마였는지, 어떤 SKU가 품절되었는지, 주문 번호 48821이 발송되었는지와 같은 질문들입니다. 합리적인 질문들입니다. 유혹적인 답변은 에이전트에게 전체 API 접근 권한을 부여하고 스스로 알아서 하게 만드는 것입니다. 하지만 그렇게 하면 LLM이 "도움이 되고자" 오타라고 생각한 것을 수정하다가 새벽 2시에 가격을 편집하는 상황을 맞이하게 됩니다.

그래서 우리는 대신 지루한 버전을 만들었습니다: woocommerce-mcp. 이는 Claude(또는 모든 MCP 클라이언트)에게 실제 WordPress + WooCommerce 스토어에 대한 읽기 권한만을 부여하며, 그 외의 권한은 전혀 주지 않는 작은 Model Context Protocol (MCP) 서버입니다. 이것은 오픈 소스(MIT)이며, 이 포스트는 설계 결정에 관한 것입니다. 왜냐하면 흥미로운 부분은 코드가 아니라, 우리가 의도적으로 제외한 것이기 때문입니다.

읽기 전용은 제한이 아니라 기능입니다

이 프로젝트 전체에서 가장 중요한 단 한 줄은 쓰기 도구(write tools)가 없다는 점입니다. "확인 후 쓰기"도 아니고, "플래그로 제어되는 쓰기"도 아닙니다. 아무것도 없습니다. 서버는 5개의 도구를 노출하며, 5개 모두 읽기 전용입니다:

도구	답변 내용
list_products	이름/SKU로 제품 검색, 가격, 재고, 퍼머링크 포함
...

그 이유는 폭발 반경(blast radius) 때문입니다. 읽기만 할 수 있는 에이전트는 재고를 초과 판매할 수 없고, 가격을 망가뜨릴 수 없으며, 프롬프트를 잘못 읽었다고 해서 주문을 취소할 수도 없습니다. 모델의 추론 과정에서 필연적으로 무언가 잘못될 때, 최악의 결과는 잘못된 답변이지 잘못된 데이터베이스가 아닙니다. 자신의 운영 중인 상점에 AI를 연결할지 결정하는 스토어 소유자에게 "물리적으로 아무것도 변경할 수 없습니다"라는 문장은 대화를 종결시키는 결정적인 한 마디가 됩니다. 나중에 인간의 확인을 거치는 별도의, 명시적으로 범위가 지정된 쓰기 경로를 별도의 프로젝트로 추가할 수는 있습니다. 기본적으로 읽기 도구에 쓰기 기능을 묶어버리는 것이 첫날부터 신뢰를 잃는 방식입니다.

코드뿐만 아니라 키(keys)의 범위도 지정하세요

읽기 전용 도구(Read-only tools)만으로는 보장의 절반에 불과합니다. 나머지 절반은 자격 증명(credential)입니다. WooCommerce REST 키는 읽기(Read), 쓰기(Write), 읽기/쓰기(Read/Write) 유형이 있습니다. README 파일은 이에 대해 단호하게 명시하고 있습니다: 반드시 읽기(Read) 권한만 있는 키를 생성하십시오. 서버는 HTTPS를 통해 쿼리 인증(query auth) 방식으로 여러분의 스토어에 키를 전송합니다. 설령 향후 버그나 프롬프트 주입(prompt-injected)된 도구 호출이 POST를 시도하더라도, WooCommerce 자체에서 해당 키를 거부할 것입니다. 무언가가 변경되려면 두 개의 독립적인 계층(쓰기 도구 없음, 쓰기 키 없음)이 모두 실패해야 합니다. 이것이 바로 실제 운영 중인 스토어(production store)가 누려야 할 수준의 편집증적 보안입니다.

search_posts는 키가 전혀 필요하지 않습니다. 공개된 WP REST API를 호출하기 때문입니다. 따라서 자격 증명을 생성하기 전이라도 어떤 WordPress 사이트를 대상으로든 이 기능을 시연해 볼 수 있습니다.

플러그인 없음, 종속성 없음

스토어에 설치할 것은 아무것도 없습니다. 서버는 WooCommerce가 이미 제공하는 REST 엔드포인트(endpoints)와 통신합니다. 이는 두 가지 이유로 중요합니다. 첫째, AI 실험을 해보기 위해 클라이언트에게 운영 중인 사이트에 PHP를 추가해 달라고 요청할 필요가 없으며, 둘째, 플러그인의 업데이트 굴레에 얽매일 필요가 없기 때문입니다. MCP 서버는 에이전트가 실행되는 곳 어디에서나 실행됩니다(stdio를 통한 로컬 실행 또는 컨테이너 실행 - Dockerfile 제공). 스토어는 그대로 유지됩니다.

의도적으로 가볍게 설계된 스택

TypeScript, 공식 @modelcontextprotocol/sdk, 도구 입력 스키마(tool input schemas)를 위한 zod, 이것이 의존성 목록의 전부입니다. stdio 전송(transport) 방식을 사용하므로, 호스팅된 엔드포인트 없이도 Claude Desktop, Cursor 또는 모든 MCP 클라이언트 설정에 바로 적용할 수 있습니다. 전체 코드는 수백 줄에 불과합니다. MCP는 작고 단일 목적을 가진 서버에 유리합니다. WooCommerce 읽기 작업을 잘 수행하는 서버는 스토어 전체를 소유하려는 모놀리스(monolith)보다 다른 도구들과 더 잘 조합됩니다.

다음 단계

읽기 전용 (read-only) 서버는 안전한 진입점입니다. 실제 프로젝트에서 이는 보통 더 큰 그림의 첫 번째 단계입니다. 즉, 동일한 카탈로그 및 재고 데이터를 반대 방향(ERP 또는 도매업체 피드)으로 동기화하는 과정으로 이어지며, 이 단계에서는 쓰기 (write) 작업이 신중하게 관리되고, 큐 (queue)에 쌓이며, 대조 (reconcile) 과정을 거칩니다. 이는 위험 프로필 (risk profile)이 다르며 별개의 소프트웨어 영역입니다. 읽기 계층 (read layer)을 분리하여 아주 쉽게 감사 (auditable)할 수 있도록 유지하는 것이 나머지 통합 과정을 안전하게 추론할 수 있게 만드는 핵심입니다.

WooCommerce 스토어를 운영 중이며 이를 시도해보고 싶다면, 리포지토리 (repo)에서 2분 만에 설정을 완료할 수 있습니다:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp && npm install && npm run build

그런 다음 WP_URL과 읽기 전용 (Read-only) WooCommerce 키를 사용하여 MCP 클라이언트를 dist/index.js로 지정하십시오.

코드, 이슈 (issues), 그리고 전체 도구 참조는 **https://github.com/wppoland/woocommerce-mcp**에서 확인할 수 있습니다. 피드백은 언제나 환영하며, 특히 다음에 어떤 읽기 전용 도구를 원하는지 알려주세요. 환불 요약 (refunds summary), 고객 조회 (customer lookup), 쿠폰 상태 (coupon status)가 저희가 가장 많이 듣는 세 가지 요청입니다.

이 프로젝트는 WPPoland 팀에 의해 제작되었습니다. 저희는 대부분의 시간을 AI 커머스의 덜 화려한 측면, 즉 재고와 가격이 정확하게 유지되도록 WooCommerce를 ERP 및 도매업체 API에 연결하는 작업에 할애하고 있습니다.