MCP 설정 가이드

모든 주요 AI 코딩 도구에 Shopify MCP 서버를 연결하기 위한 단계별 안내입니다. 각 가이드는 설치, 설정, 확인, 문제 해결을 다룹니다.

권장 설정

최상의 Shopify 개발 경험을 위해 두 개의 MCP 서버를 구성하세요:

Shopify Dev MCP -- 문서, API 스키마, Liquid 레퍼런스 (인증 불필요)
Shopify Store MCP -- Admin API를 통한 라이브 스토어 관리 (액세스 토큰 필요)

이 가이드에서 두 가지 모두를 다룹니다.

사전 요구 사항

설정을 시작하기 전에 다음을 준비하세요:

Node.js 18+ -- nodejs.org에서 다운로드
npm 9+ -- Node.js와 함께 제공
Shopify Partner 계정 -- 무료 가입
개발 스토어 -- Partner 대시보드에서 생성

Node.js 설치를 확인하세요:

node --version   # Should output v18.x.x or higher
npm --version    # Should output 9.x.x or higher
npx --version    # Should output 9.x.x or higher

Shopify 액세스 토큰 생성

스토어 관리 MCP 서버에는 Admin API 액세스 토큰이 필요합니다:

Shopify 스토어 관리자로 이동합니다
설정 > 앱 및 판매 채널로 이동합니다
앱 개발을 클릭합니다 (개발자 접근을 먼저 활성화해야 할 수 있습니다)
앱 만들기를 클릭하고 "MCP Integration"과 같은 이름을 지정합니다
Admin API 범위 구성을 클릭합니다
필요한 범위를 선택합니다:

범위	용도
`read_products`, `write_products`	상품 관리
`read_orders`, `write_orders`	주문 관리
`read_customers`, `write_customers`	고객 데이터
`read_inventory`, `write_inventory`	재고 추적
`read_fulfillments`, `write_fulfillments`	발송 처리

저장을 클릭한 다음 앱 설치를 클릭합니다
Admin API 액세스 토큰을 복사합니다 -- 한 번만 표시됩니다

토큰 보안

액세스 토큰을 절대 버전 관리에 커밋하지 마세요
스크린샷, 채팅, 문서에서 토큰을 절대 공유하지 마세요
환경 변수나 시크릿 매니저에 토큰을 저장하세요
토큰을 주기적으로 교체하세요
최소 필요 범위를 사용하세요

Claude Code (권장)

Claude Code는 내장 서버 관리 명령어가 있는 최고의 MCP 통합을 제공합니다.

1단계: Dev MCP 서버 추가

claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

2단계: Store MCP 서버 추가

claude mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

환경 변수 대안

토큰을 인라인으로 전달하는 대신 셸 프로필에 설정할 수 있습니다:

# Add to ~/.zshrc or ~/.bashrc
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"
export MYSHOPIFY_DOMAIN="your-store.myshopify.com"

그런 다음 -e 플래그 없이 서버를 추가합니다:

claude mcp add shopify-store -- npx -y shopify-mcp@latest

서버가 환경에서 자동으로 읽습니다.

3단계: 확인

# List configured MCP servers
claude mcp list

# Start Claude Code and test
claude

Claude Code에서 다음 프롬프트를 시도하세요:

# Test Dev MCP
Search the Shopify docs for product creation best practices

# Test Store MCP
List the first 5 products in my store

범위 옵션

# Project scope (default) - only available in this project
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# User scope - available in all projects
claude mcp add --scope user shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

서버 관리

# List all servers
claude mcp list

# Remove a server
claude mcp remove shopify-dev

# View server details
claude mcp get shopify-dev

Cursor

1단계: 설정 파일 찾기

OS	경로
macOS	`~/.cursor/mcp.json`
Linux	`~/.cursor/mcp.json`
Windows	`%APPDATA%\Cursor\mcp.json`

파일이 존재하지 않으면 생성하세요.

2단계: 서버 설정 추가

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

3단계: Cursor 재시작

설정 파일 저장 후 Cursor를 완전히 재시작하세요 (창 새로고침만으로는 안 됩니다).

4단계: 확인

Composer 패널을 엽니다 (Cmd+I / Ctrl+I)
MCP 서버 아이콘을 찾습니다 (보통 렌치 또는 플러그 아이콘)
클릭하여 사용 가능한 도구를 확인합니다
쿼리를 시도합니다: "Search Shopify docs for webhook topics"

Cursor 관련 팁

Cursor는 첫 실행 시 MCP 서버를 초기화하는 데 10-15초가 소요될 수 있습니다
도구가 표시되지 않으면 Cursor 출력 패널에서 MCP 관련 오류를 확인하세요
MCP와 함께 Shopify 관련 컨텍스트를 추가하려면 Cursor의 .cursorrules 파일을 사용하세요

Claude Desktop

macOS 설정

1단계: 설정 파일 열기

# Create the config directory if needed
mkdir -p ~/Library/Application\ Support/Claude

# Open or create the config file
open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

2단계: 설정 추가

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

3단계: Claude Desktop 재시작

Claude Desktop을 완전히 종료하고 다시 엽니다.

4단계: 확인

채팅 입력란에서 망치 아이콘을 찾으세요. 클릭하면 사용 가능한 MCP 도구를 확인할 수 있습니다.

Windows 설정

1단계: 설정 파일 열기

# Open or create the config file
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

2단계: 설정 추가

위의 macOS와 동일한 JSON 설정을 사용하세요.

3단계: 재시작 및 확인

Claude Desktop을 재시작하고 망치 아이콘을 확인하세요.

Windows 관련 참고사항

Windows PATH 문제

Windows에서 npx를 찾을 수 없는 경우 전체 경로를 지정하세요:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    }
  }
}

Codex (OpenAI)

OpenAI의 Codex CLI는 도구 확장을 위해 MCP 서버를 지원합니다.

1단계: Codex 설치

npm install -g @openai/codex

2단계: MCP 서버 추가

# Add Dev MCP
codex mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Add Store MCP
codex mcp add shopify-store \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxx \
  -e MYSHOPIFY_DOMAIN=your-store.myshopify.com \
  -- npx -y shopify-mcp@latest

3단계: 확인

codex mcp list
codex  # Start Codex and test with a Shopify query

Codex 관련 참고사항

Codex는 Claude 기반 클라이언트와 도구 호출을 다르게 처리할 수 있습니다
복잡한 워크플로우를 구축하기 전에 각 도구를 개별적으로 테스트하세요
일부 커뮤니티 MCP 서버는 Codex와 호환성 차이가 있을 수 있습니다

Windsurf

1단계: 설정 찾기

Windsurf는 설정에 MCP 구성을 저장합니다. 설정을 열고 (Cmd+, / Ctrl+,) "MCP"를 검색하거나 MCP 설정 파일을 찾으세요:

OS	경로
macOS	`~/.windsurf/mcp.json`
Linux	`~/.windsurf/mcp.json`
Windows	`%APPDATA%\Windsurf\mcp.json`

2단계: 설정 추가

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      }
    }
  }
}

3단계: 재시작 및 확인

Windsurf를 재시작하고 AI 패널에 MCP 도구가 나타나는지 확인하세요.

Cline

Cline (VS Code 확장)은 설정을 통해 MCP 서버를 지원합니다.

1단계: Cline 설정 열기

Cline이 설치된 VS Code에서:

명령 팔레트를 엽니다 (Cmd+Shift+P / Ctrl+Shift+P)
"Cline: MCP Servers"를 검색합니다
또는 설정 파일을 직접 편집합니다

설정 파일 위치:

OS	경로
macOS	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Linux	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Windows	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

2단계: 설정 추가

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"],
      "disabled": false
    },
    "shopify-store": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx",
        "MYSHOPIFY_DOMAIN": "your-store.myshopify.com"
      },
      "disabled": false
    }
  }
}

3단계: 확인

VS Code를 새로고침합니다 (Cmd+Shift+P > "Developer: Reload Window")
Cline 사이드바를 엽니다
MCP 서버 상태 표시기를 확인합니다
다음으로 테스트합니다: "List my Shopify MCP tools"

문제 해결

"Cannot find module" 오류

Error: Cannot find module '@anthropic-ai/shopify-dev-mcp'

원인 및 해결 방법:

Node.js 버전이 너무 오래됨:

node --version  # Must be 18+
# If outdated, update via nvm:
nvm install 18
nvm use 18

npx 캐시 손상:

# Clear npm cache
npm cache clean --force
# Try again
npx -y @anthropic-ai/shopify-dev-mcp@latest

네트워크/프록시 문제:

# Test npm registry access
npm ping
# If behind a proxy:
npm config set proxy http://proxy.example.com:8080

서버가 시작되었지만 도구가 표시되지 않음

서버가 실행 중인지 확인:

# Claude Code
claude mcp list
# Look for status: "connected" vs "disconnected"

서버 로그 확인:

Claude Desktop에서 다음 위치의 로그를 확인하세요:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\Logs\mcp*.log

일반적인 해결 방법: AI 클라이언트를 완전히 재시작하세요 (새로고침만으로는 안 됩니다).

인증 오류

Error: 401 Unauthorized

해결 방법:

토큰 만료 또는 폐기: Shopify 관리자에서 새 토큰을 생성하세요
잘못된 도메인 형식: your-store.myshopify.com을 사용하세요 (커스텀 도메인이 아님)
범위 부족: 토큰이 필요한 API 범위를 가지고 있는지 확인하세요

환경 변수 미설정:

# Verify the variable is set
echo $SHOPIFY_ACCESS_TOKEN
# If empty, set it:
export SHOPIFY_ACCESS_TOKEN="shpat_xxxxxxxxxxxxx"

속도 제한

Error: 429 Too Many Requests

Shopify의 Admin API에는 속도 제한이 있습니다 (일반적으로 표준 플랜의 경우 초당 40개 요청). 속도 제한에 도달한 경우:

요청 속도를 줄이세요 -- 대량 작업을 빠르게 연속으로 실행하지 마세요
플랜을 확인하세요 -- Shopify Plus 스토어는 더 높은 제한이 있습니다
대량 작업을 사용하세요 -- 일부 MCP 서버는 대규모 데이터셋에 대한 GraphQL 대량 작업을 지원합니다
사용량을 모니터링하세요 -- 응답의 X-Shopify-Shop-Api-Call-Limit 헤더를 확인하세요

느린 서버 시작

npx를 사용하는 MCP 서버는 첫 실행 시 패키지를 다운로드합니다. 이후 실행에서는 npm 캐시를 사용합니다.

시작 속도 향상:

# Pre-install the package globally
npm install -g @anthropic-ai/shopify-dev-mcp
npm install -g shopify-mcp

# Then reference the local binary instead of npx
claude mcp add shopify-dev -- shopify-dev-mcp

다중 스토어

여러 Shopify 스토어에 연결하려면 별도의 MCP 서버 항목을 추가하세요:

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/shopify-dev-mcp@latest"]
    },
    "store-production": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_prod_token",
        "MYSHOPIFY_DOMAIN": "my-store.myshopify.com"
      }
    },
    "store-staging": {
      "command": "npx",
      "args": ["-y", "shopify-mcp@latest"],
      "env": {
        "SHOPIFY_ACCESS_TOKEN": "shpat_staging_token",
        "MYSHOPIFY_DOMAIN": "my-store-staging.myshopify.com"
      }
    }
  }
}

프로덕션 안전

프로덕션과 스테이징 스토어에 모두 연결되어 있을 때, 프롬프트에서 항상 대상 스토어를 명시하세요. 개발 중에는 프로덕션 토큰에 읽기 전용 범위를 사용하는 것을 고려하세요.

서버 버전 충돌

업데이트 후 예상치 못한 동작이 발생하는 경우:

# Clear npm cache and reinstall
npm cache clean --force

# Claude Code: remove and re-add
claude mcp remove shopify-dev
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@latest

# Pin to a specific version if needed
claude mcp add shopify-dev -- npx -y @anthropic-ai/shopify-dev-mcp@1.2.3

설정 레퍼런스

환경 변수

변수	사용처	설명
`SHOPIFY_ACCESS_TOKEN`	Store MCP 서버	Admin API 액세스 토큰
`MYSHOPIFY_DOMAIN`	shopify-mcp (GeLi2001)	스토어 도메인 (예: `store.myshopify.com`)
`SHOP_DOMAIN`	@ajackus/shopify-mcp-server	스토어 도메인
`SHOPIFY_STOREFRONT_TOKEN`	Storefront 지원 서버	Storefront API 토큰
`COMPOSIO_API_KEY`	Composio	Composio 플랫폼 키
`ADZVISER_API_KEY`	Adzviser	Adzviser 플랫폼 키

전송 방식 (Transport)

전송 방식	설명	사용 사례
`stdio`	표준 I/O (로컬 프로세스)	대부분의 설정에서 기본값. 서버가 로컬에서 실행됩니다.
`streamable-http`	스트리밍 지원 HTTP	원격/호스팅 MCP 서버
`sse`	Server-Sent Events (레거시)	오래된 원격 서버

대부분의 커뮤니티 서버는 stdio 전송 방식을 사용하며, 이는 AI 클라이언트가 관리하는 로컬 프로세스로 서버가 실행됨을 의미합니다. 포트 포워딩이나 네트워크 설정이 필요하지 않습니다.

사전 요구 사항​

Shopify 액세스 토큰 생성​

Claude Code (권장)​

1단계: Dev MCP 서버 추가​

2단계: Store MCP 서버 추가​

3단계: 확인​

범위 옵션​

서버 관리​

Cursor​

1단계: 설정 파일 찾기​

2단계: 서버 설정 추가​

3단계: Cursor 재시작​

4단계: 확인​

Cursor 관련 팁​

Claude Desktop​

macOS 설정​

1단계: 설정 파일 열기​

2단계: 설정 추가​

3단계: Claude Desktop 재시작​

4단계: 확인​

Windows 설정​

1단계: 설정 파일 열기​

2단계: 설정 추가​

3단계: 재시작 및 확인​

Windows 관련 참고사항​

Codex (OpenAI)​

1단계: Codex 설치​

2단계: MCP 서버 추가​

3단계: 확인​

Codex 관련 참고사항​

Windsurf​

1단계: 설정 찾기​

2단계: 설정 추가​

3단계: 재시작 및 확인​

Cline​

1단계: Cline 설정 열기​

2단계: 설정 추가​

3단계: 확인​

문제 해결​

"Cannot find module" 오류​

서버가 시작되었지만 도구가 표시되지 않음​

인증 오류​

속도 제한​

느린 서버 시작​

다중 스토어​

서버 버전 충돌​

설정 레퍼런스​

환경 변수​

전송 방식 (Transport)​

사전 요구 사항

Shopify 액세스 토큰 생성

Claude Code (권장)

1단계: Dev MCP 서버 추가

2단계: Store MCP 서버 추가

3단계: 확인

범위 옵션

서버 관리

Cursor

1단계: 설정 파일 찾기

2단계: 서버 설정 추가

3단계: Cursor 재시작

4단계: 확인

Cursor 관련 팁

Claude Desktop

macOS 설정

1단계: 설정 파일 열기

2단계: 설정 추가

3단계: Claude Desktop 재시작

4단계: 확인

Windows 설정

1단계: 설정 파일 열기

2단계: 설정 추가

3단계: 재시작 및 확인

Windows 관련 참고사항

Codex (OpenAI)

1단계: Codex 설치

2단계: MCP 서버 추가

3단계: 확인

Codex 관련 참고사항

Windsurf

1단계: 설정 찾기

2단계: 설정 추가

3단계: 재시작 및 확인

Cline

1단계: Cline 설정 열기

2단계: 설정 추가

3단계: 확인

문제 해결

"Cannot find module" 오류

서버가 시작되었지만 도구가 표시되지 않음

인증 오류

속도 제한

느린 서버 시작

다중 스토어

서버 버전 충돌

설정 레퍼런스

환경 변수

전송 방식 (Transport)