Ecommerce MCP Automation

Claude Code + MCP 連携のサンプル: Shopify と Meta Ads を MCP ツールとして公開し、さらにレポーティングエージェントが両方のデータを取得して、1 つの整形された日次 P&L + 広告パフォーマンスのスプレッドシートにまとめます — プラットフォーム間での手動コピー＆ペーストは不要です。

これは、公開されている Shopify Admin API と Meta Marketing API のドキュメントに基づいて構築されたデモであり、実際のビジネスで運用されたものではありません。クリーンルームサンプルです。実際のエンドポイント、実際の認証、実際のページネーション、実際のエラーハンドリングを、この種の自動化がどのように構築されるかを正確に示すために新規に記述しています。認証情報ゼロのモックモードでエンドツーエンドに動作し（実際のレスポンスの代わりに現実的なフィクスチャデータを使用）、実際の認証情報が設定された瞬間に統合単位でライブモードに切り替わります — 実行方法 を参照してください。

Shopify クライアントは、実際の Shopify Partners 開発ストア（本番ビジネスではなくサンドボックスストア）に対してライブで実行済みです。実際の認証、実際の注文、実際の API レスポンスです。このプロセスで、モックフィクスチャだけではカバーできなかった null 許容に関する実際のエッジケースが 2 つ発見され、修正されました（既知の簡略化 を参照）。Meta Ads はこのリポジトリではデフォルトでモックトランスポートに対して実行されます。クライアントコードも同様に記述されており、META_ACCESS_TOKEN/META_AD_ACCOUNT_ID が設定された瞬間にライブへ切り替わります。

できること

• Shopify の注文、売上、COGS を MCP ツールとして公開（get_orders、get_daily_pnl）

• Meta Ads の広告費、インプレッション、購入、ROAS を MCP ツールとして公開（get_insights、get_daily_ad_performance）

• レポーティングエージェント（daily_report.py）が両方を同時に取得し、整形された .xlsx — Summary、Orders、Ad Performance シート — を書き出します

• ワークフロー全体を自然言語トリガー（「日次レポートを実行」）で起動できる 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

2 つの API クライアント（clients/shopify_client.py、clients/meta_ads_client.py）は本物の統合コードです。実際のエンドポイント URL、実際の認証ヘッダー、実際のページネーションループ、実際の 429 バックオフを備えています。モックモードとライブモードの間で唯一変わるのは、HTTP トランスポート（clients/http.py）です。

• ライブ: httpx.AsyncClient が Shopify / Meta への実際の接続を開きます。

• モック: httpx.AsyncClient には、インプロセスの FastAPI アプリ（fixtures/mock_api.py）を指す httpx.ASGITransport が与えられます。このアプリは現実的なフィクスチャペイロードを提供します。ポートはバインドされず、サブプロセスも実行されませんが、リクエストは実際の HTTP/ASGI ルーティング、ヘッダー、JSON エンコーディングを経由します。

つまり、レビュアーが読むクライアントコードは、ライブストアに対して実行されるコードと同じものです。モックを本物に見せかけたものではありません。詳細な規約は CLAUDE.md を参照してください。

実行方法

モックモード（デフォルト — 認証情報なし）

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

ライブモード

.env.example を .env にコピーし、お持ちの認証情報を記入してください — 各統合は、自身の認証情報が存在する瞬間に独立してライブに切り替わります。つまり、Meta をモックのまま Shopify をライブで実行できます（逆も同様です）。

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 設定（Claude Code の場合は .mcp.json、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 広告パフォーマンスを取得して」などと尋ねてください。デフォルトではモックモードで、ツールを直接呼び出します。

スキルとして

skills/daily-report/SKILL.md はレポート生成ワークフローをラップしており、正確な CLI コマンドを必要とせず、自然言語トリガー（「日次レポートを実行」）で Claude Code が実行できます。フルレポートのパスでは、上記の MCP 設定は一切不要です — daily_report.py を直接実行し、クライアントをプレーンな Python として呼び出すだけなので、MCP は関与しません。MCP 設定が必要なのは、スキルのもう 1 つのパス、つまりレポート全体を実行する代わりに 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 は、実際の 2 ホップルックアップ（variant → inventory_item_id → バッチ取得した inventory_items）を介して Shopify の InventoryItem.cost フィールドを使用します — Shopify は注文のラインアイテムにコストを直接公開していません。ライブストアでは、cost とラインアイテムの sku はどちらも null 許容です（マーチャントが設定していない可能性があります）。これはドキュメントだけでなく、実際の開発ストアに対するライブテストで発見されました。どちらもエラーにするのではなく、コストゼロ / SKU なしとして処理されます。

• 返金済みの注文 は、daily_pnl() の売上 / COGS / 注文数から完全に除外されます。部分返金・返品の会計処理には Refund リソースが必要になります — ここでは対象外です。

• Meta の購入アトリビューション は、広告アカウントで設定されているアトリビューションウィンドウに基づき、actions/action_values 配列の purchase アクションタイプを使用します — このクライアントはそれを上書きしません。

• レポーティングエージェントは現在、日付範囲でフィルタリングせず、利用可能な注文 / インサイトをすべて取得します。本番の日次 cron では、対象日の created_at_min/time_range を渡すことになるでしょう。

ライセンス

MIT — LICENSE を参照してください。