Shopify용 커스텀 MCP 서버 구축
기존 MCP 서버는 일반적인 사용 사례를 다루지만, 모든 Shopify 비즈니스에는 고유한 요구사항이 있습니다. 재고 데이터와 독자적인 수요 예측 모델을 결합하는 MCP 서버가 필요할 수 있습니다. 또는 제품 생성 시 특정 비즈니스 규칙을 적용하는 서버가 필요할 수 있습니다. 혹은 Shopify를 내부 ERP 시스템과 통합하는 서버가 필요할 수도 있습니다.
이 가이드에서는 공식 TypeScript SDK를 사용하여 커스텀 MCP 서버를 처음부터 구축하고, Shopify Admin API 도구를 구현하고, 팀을 위해 게시하는 방법을 안내합니다.
커스텀 구축과 기존 서버 사용 시점
다음과 같은 경우 커스텀 MCP 서버를 구축합니다:
- 기존 서버가 사용 사례를 다루지 못하는 경우: Shopify 데이터와 내부 시스템을 결합하는 도구가 필요
- 비즈니스 로직 적용이 필요한 경우: 제품 생성이 특정 명명 규칙, 가격 책정 규칙 또는 승인 워크플로를 따라야 함
- 보안 요구사항이 요구하는 경우: 어떤 API 작업을 노출할지 정확히 제어하고 사용 현황을 감사해야 함
- 도메인별 추상화가 필요한 경우: 원시 CRUD가 아닌 비즈니스 프로세스를 인코딩한 "create_seasonal_collection" 같은 도구가 필요
- 성능 최적화: 일반 서버가 지원하지 않는 방식으로 Shopify API 호출을 배치 처리하거나 캐시해야 함
다음과 같은 경우 기존 서버를 사용합니다:
- 표준 CRUD 작업으로 충분한 경우
- 프로토타이핑이나 탐색 중인 경우
- 커뮤니티 서버가 적극적으로 유지보수되고 요구사항을 충족하는 경우
커뮤니티 shopify-mcp 서버를 80%의 요구(표준 작업)에 사용하고, 비즈니스 고유의 20%를 위해 커스텀 서버를 구축하세요. 이들은 동시에 실행할 수 있습니다 -- Claude Code는 여러 MCP 서버를 지원합니다.
MCP SDK 설정 (TypeScript)
프로젝트 초기화
mkdir shopify-custom-mcp
cd shopify-custom-mcp
npm init -y
npm install @modelcontextprotocol/sdk @shopify/shopify-api zod
npm install -D typescript @types/node tsx
npx tsc --init
tsconfig.json을 업데이트합니다:
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"declaration": true
},
"include": ["src/**/*"]
}
package.json을 업데이트합니다:
{
"name": "shopify-custom-mcp",
"version": "1.0.0",
"type": "module",
"bin": {
"shopify-custom-mcp": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts",
"start": "node dist/index.js"
}
}
기본 서버 구조
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// 명령줄 인수 파싱
const args = process.argv.slice(2);
const accessToken = args.find(a => a.startsWith("--token="))?.split("=")[1]
|| process.env.SHOPIFY_ACCESS_TOKEN;
const storeDomain = args.find(a => a.startsWith("--domain="))?.split("=")[1]
|| process.env.SHOPIFY_STORE_DOMAIN;
if (!accessToken || !storeDomain) {
console.error("Usage: shopify-custom-mcp --token=shpat_xxx --domain=store.myshopify.com");
process.exit(1);
}
// MCP 서버 생성
const server = new McpServer({
name: "shopify-custom-mcp",
version: "1.0.0",
});
// Shopify API 헬퍼
async function shopifyGraphQL(query: string, variables?: Record<string, unknown>) {
const response = await fetch(
`https://${storeDomain}/admin/api/2025-01/graphql.json`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Shopify-Access-Token": accessToken!,
},
body: JSON.stringify({ query, variables }),
}
);
if (!response.ok) {
throw new Error(`Shopify API error: ${response.status} ${response.statusText}`);
}
return response.json();
}
// --- 여기서 도구, 리소스, 프롬프트를 등록합니다 ---
// (아래 섹션 참조)
// stdio 전송으로 서버 시작
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Shopify Custom MCP server running on stdio");
}
main().catch(console.error);
Shopify Admin API 도구 구현
도구 1: 저재고 제품 조회
이 도구는 Shopify 쿼리와 비즈니스 로직(커스텀 임계값)을 결합합니다:
// 저재고 제품을 찾는 도구 등록
server.tool(
"get_low_inventory_products",
"Find products where total inventory is below a threshold",
{
threshold: z.number().default(10).describe("Inventory threshold (default: 10)"),
location_id: z.string().optional().describe("Filter by location ID (optional)"),
},
async ({ threshold, location_id }) => {
// ... (코드 블록은 영어 원본과 동일)
}
);
전체 코드 구현은 영어 원본과 동일합니다. 위 구조에서 비즈니스 로직은 모든 제품을 페이지네이션으로 조회한 후 임계값으로 필터링합니다.
도구 2: 비즈니스 규칙에 따른 제품 생성
이 도구는 회사의 제품 생성 표준을 적용합니다. 비즈니스 규칙에는 타이틀 케이스 형식 지정, 카테고리별 SKU 접두사 자동 생성, 최소 설명 길이 검증, 표준 가격 등급으로 조정이 포함됩니다.
리소스 추가
리소스는 AI가 Shopify 스토어 구성을 이해하는 데 도움이 되는 읽기 전용 컨텍스트를 제공합니다. 정적 리소스(스토어 구성)와 동적 리소스(실시간 스토어 요약)를 포함합니다.
프롬프트 추가
프롬프트는 일반적인 워크플로를 위한 재사용 가능한 대화 시작 템플릿을 제공합니다. 주간 재고 보고서와 신제품 출시 워크플로가 포함됩니다.
MCP Inspector로 테스트
MCP Inspector는 AI 호스트에 연결하지 않고도 서버와 상호작용할 수 있는 시각적 테스트 도구입니다.
설치 및 실행
npx @modelcontextprotocol/inspector tsx src/index.ts -- --token=shpat_xxx --domain=store.myshopify.com
이렇게 하면 다음을 수행할 수 있는 웹 인터페이스가 열립니다:
- 사용 가능한 도구 보기: 등록된 모든 도구와 해당 스키마 확인
- 도구 호출 테스트: 매개변수를 입력하고 도구 실행
- 응답 검사: 각 도구의 JSON 응답 확인
- 리소스 확인: 등록된 리소스 탐색 및 읽기
- 프롬프트 테스트: 프롬프트를 실행하고 생성된 메시지 확인
MCP 서버를 Claude Code에 연결하기 전에 반드시 Inspector로 테스트하세요. AI 대화의 오버헤드 없이 스키마 오류, 인증 문제, 런타임 오류를 잡을 수 있습니다.
게시
팀을 위한 게시 (npm)
npm run build
npm publish
팀원 설치:
claude mcp add your-custom-mcp -- npx -- -y shopify-custom-mcp --token=shpat_xxx --domain=store.myshopify.com
팀을 위한 게시 (Git)
npm에 게시하지 않으려면 팀원이 리포지토리에서 직접 사용할 수 있습니다:
claude mcp add custom-shopify -- npx -- tsx /path/to/shopify-custom-mcp/src/index.ts -- --token=shpat_xxx --domain=store.myshopify.com
Docker 배포 (SSE 전송)
공유 팀 서버의 경우 전송을 SSE로 변경하고 Docker로 배포할 수 있습니다.
MCP 서버를 네트워크 서비스(SSE 또는 HTTP)로 배포하면 Shopify 스토어의 Admin API에 직접 접근할 수 있습니다. 반드시 다음을 수행하세요:
- 인증 뒤에서 실행 (API 키, OAuth 또는 VPN)
- 프로덕션 환경에서 HTTPS 사용
- 감사를 위해 모든 도구 호출을 로그로 기록
- 수신 연결 속도 제한
- 인증 없이 공개 인터넷에 노출하지 않기
전체 프로젝트 구조
shopify-custom-mcp/
src/
index.ts # 메인 진입점 (서버 + 도구 + 리소스 + 프롬프트)
__tests__/
tools.test.ts # 비즈니스 로직 단위 테스트
dist/ # 컴파일 출력
package.json
tsconfig.json
README.md
더 큰 서버의 경우 도구를 별도의 파일로 분리합니다:
shopify-custom-mcp/
src/
index.ts # 서버 설정 및 전송
shopify-client.ts # 공유 Shopify API 헬퍼
tools/
inventory.ts # 재고 관련 도구
products.ts # 제품 관련 도구
orders.ts # 주문 관련 도구
resources/
store-config.ts # 정적 스토어 구성
store-summary.ts # 동적 스토어 데이터
prompts/
reports.ts # 보고서 생성 프롬프트
workflows.ts # 워크플로 프롬프트
__tests__/
inventory.test.ts
products.test.ts
요약
TypeScript SDK를 사용하여 Shopify용 커스텀 MCP 서버를 구축하는 것은 간단합니다. 핵심 단계는 다음과 같습니다:
- MCP SDK와 Shopify API 클라이언트로 프로젝트를 초기화
- 비즈니스 로직과 Shopify API 호출을 캡슐화하는 도구를 구현
- 정적 구성과 동적 스토어 데이터를 위한 리소스를 추가
- 일반적인 워크플로 템플릿을 위한 프롬프트를 추가
- MCP Inspector와 단위 테스트로 테스트
- 팀의 요구에 따라 npm, Git 또는 Docker로 배포
이 투자는 빠르게 성과를 냅니다 -- 5-10개의 잘 설계된 도구를 가진 커스텀 MCP 서버는 비즈니스 규칙이 내장된 상태로 AI 어시스턴트에게 Shopify 스토어에 대한 직접적이고 제어된 접근을 제공함으로써 매주 수 시간의 반복적인 작업을 절약할 수 있습니다.