Ecommerce MCP Automation

Claude Code + MCP 통합 샘플: Shopify 및 Meta Ads를 MCP 도구로 노출하고, 두 플랫폼의 데이터를 하나의 서식화된 일일 P&L + 광고 성과 스프레드시트로 모아주는 리포팅 에이전트를 포함합니다 — 플랫폼 간 수동 복사-붙여넣기가 필요 없습니다.

이 데모는 공개 Shopify Admin API 및 Meta Marketing API 문서를 기반으로 구축된 시연용입니다 — 실제 비즈니스에서 운영된 적이 없습니다. 실제 엔드포인트, 실제 인증, 실제 페이지네이션, 실제 오류 처리를 사용하는 클린룸 샘플로, 이런 자동화가 어떻게 구축되는지 정확히 보여주기 위해 새로 작성되었습니다. 자격 증명 없이 mock 모드로 엔드투엔드 실행되며 (실제 응답 대신 현실적인 픽스처 데이터 사용), 실제 자격 증명이 설정되는 즉시 통합별로 live 모드로 전환됩니다 — 실행 방법을 참조하세요.

Shopify 클라이언트는 실제 Shopify Partners 개발 스토어(프로덕션 비즈니스가 아닌 샌드박스 스토어)를 대상으로 live 실행된 적이 있습니다 — 실제 인증, 실제 주문, 실제 API 응답을 사용했습니다. 이 과정에서 mock 픽스처만으로는 발견되지 않았던 실제 null 허용(nullability) 엣지 케이스 두 건이 발견되어 수정되었습니다(알려진 단순화 참조). Meta Ads는 이 저장소에서 기본적으로 mock 전송 계층으로 실행됩니다. 클라이언트 코드는 동일한 방식으로 작성되며 META_ACCESS_TOKEN/META_AD_ACCOUNT_ID가 설정되는 즉시 live로 전환됩니다.

기능

• Shopify 주문, 매출, COGS를 MCP 도구로 노출합니다 (get_orders, get_daily_pnl)

• Meta Ads 지출, 노출, 구매, ROAS를 MCP 도구로 노출합니다 (get_insights, get_daily_ad_performance)

• 두 데이터를 동시에 가져와 서식화된 .xlsx — Summary, Orders, Ad Performance 시트 — 를 작성하는 리포팅 에이전트(daily_report.py)를 실행합니다

• 전체 워크플로를 자연어 트리거("일일 리포트 실행")로 실행할 수 있게 해주는 Claude Code Skill을 제공합니다

• 아무것도 실행하지 않아도 결과를 확인할 수 있도록 커밋된 샘플 출력을 포함합니다

Related MCP server: ads-mcp

샘플 출력

Summary 탭의 렌더링 미리보기 — 실제 파일(Orders 및 Ad Performance 시트, 통화/ROAS 서식, 고정된 헤더 행 포함)은 실제 생성된 워크북 열기로 확인하세요.

아키텍처

flowchart LR
    subgraph Shopify["Shopify Admin API"]
        SO[orders.json]
        SI[inventory_items.json]
    end
    subgraph Meta["Meta Marketing API"]
        MI[act_id/insights]
    end

    SO --> SC[shopify_client.py]
    SI --> SC
    MI --> MC[meta_ads_client.py]

    SC --> SS[shopify_server.py<br/>MCP tools]
    MC --> MS[meta_ads_server.py<br/>MCP tools]

    SC --> DR[daily_report.py]
    MC --> DR
    DR --> SPX[spreadsheet.py]
    SPX --> XLSX[(sample_daily_report.xlsx)]

    Mock[["mock_api.py<br/>(ASGITransport, in-process)"]] -.mock mode.-> SC
    Mock -.mock mode.-> MC

두 API 클라이언트(clients/shopify_client.py, clients/meta_ads_client.py)는 실제 통합 코드입니다 — 실제 엔드포인트 URL, 실제 인증 헤더, 실제 페이지네이션 루프, 실제 429 백오프를 사용합니다. mock 모드와 live 모드 사이에서 바뀌는 유일한 부분은 HTTP 전송 계층(clients/http.py)입니다:

• Live: httpx.AsyncClient가 Shopify / Meta에 실제 연결을 엽니다.

• Mock: httpx.AsyncClient에는 현실적인 픽스처 페이로드를 제공하는 프로세스 내부 FastAPI 앱(fixtures/mock_api.py)을 가리키는 httpx.ASGITransport가 주어집니다. 포트가 바인딩되지 않고 서브프로세스도 실행되지 않지만 — 요청은 여전히 실제 HTTP/ASGI 라우팅, 헤더, JSON 인코딩을 거칩니다.

즉, 리뷰어가 읽는 클라이언트 코드는 live 스토어에서 실행될 코드와 동일한 코드입니다 — mock을 실제처럼 꾸민 것이 아닙니다. 전체 규칙은 CLAUDE.md를 참조하세요.

실행 방법

Mock 모드 (기본 — 자격 증명 불필요)

git clone <this-repo> && cd ecommerce-mcp-automation
python -m venv .venv && source .venv/bin/activate   # or: uv sync && source .venv/bin/activate
pip install -e ".[dev]"

python -m ecommerce_mcp.reporting.daily_report
# -> Wrote examples/sample_daily_report.xlsx

테스트 스위트도 같은 방식으로 실행합니다. 설정이 필요 없습니다:

pytest

Live 모드

.env.example를 .env로 복사하고 보유한 값을 입력하세요 — 각 통합은 자체 자격 증명이 있는 즉시 독립적으로 live로 전환되므로, Meta는 여전히 mock으로 둔 채 Shopify만 live로 실행할 수 있습니다(반대의 경우도 마찬가지):

cp .env.example .env
# SHOPIFY_STORE_DOMAIN=your-dev-store.myshopify.com
# SHOPIFY_ACCESS_TOKEN=shpat_...          (Partners dev store -> custom app -> Admin API token)
# META_ACCESS_TOKEN=EAA...                (System User token, ads_read scope)
# META_AD_ACCOUNT_ID=act_1234567890

MCP 서버로 사용 (Claude Code / Claude Desktop)

MCP 구성(.mcp.json — Claude Code용, 또는 Claude Desktop의 구성 파일)에 추가하세요. command를 프로젝트의 venv 인터프리터로 직접 지정하세요 — MCP 클라이언트는 셸 프로파일을 소스하지 않으므로, 그냥 python만으로는 활성화된 venv를 인식하지 못합니다:

{
  "mcpServers": {
    "shopify": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.shopify_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    },
    "meta-ads": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.meta_ads_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    }
  }
}

그런 다음 Claude에게 "오늘 Shopify P&L이 어떻게 되나요?" 또는 "어제 Meta 광고 성과를 알려줘" 같은 질문을 해보세요 — Claude가 기본적으로 mock 모드에서 도구를 직접 호출할 것입니다.

Skill로 사용

skills/daily-report/SKILL.md는 리포트 생성 워크플로를 감싸서, 정확한 CLI 명령어가 없어도 Claude Code가 자연어 트리거("일일 리포트 실행")로 실행할 수 있게 해줍니다. 전체 리포트 경로는 위의 MCP 구성이 전혀 필요 없습니다 — daily_report.py를 직접 실행하며, 이 스크립트는 MCP 없이 클라이언트를 일반 Python으로 호출합니다. MCP 구성은 Skill의 다른 경로에서만 필요합니다: 전체 리포트를 실행하는 대신 get_daily_pnl / get_daily_ad_performance를 MCP 도구로 호출하여 일회성 단일 지표 질문("오늘 ROAS는 얼마인가요?")에 답하는 경우입니다.

프로젝트 구조

src/ecommerce_mcp/
  clients/         Typed, async API clients (Shopify + Meta), transport-swappable
  mcp_servers/      MCP tool servers wrapping the clients
  reporting/        daily_report.py (orchestration) + spreadsheet.py (openpyxl)
  fixtures/         Realistic mock payloads + the in-process mock API app
skills/daily-report/ Claude Code Skill for the reporting workflow
tests/              pytest suite (all run against mock mode)
examples/           Committed sample .xlsx + README preview image

알려진 단순화

숨기지 않고 여기에 문서화합니다. 이런 샘플에서는 겉꾸밈보다 정확성이 더 중요하기 때문입니다:

• COGS는 실제 두 단계 조회(variant → inventory_item_id → 배치 inventory_items 가