Ecommerce MCP Automation

A sample Claude Code + MCP integration: Shopify and Meta Ads exposed as MCP tools, plus a reporting agent that pulls both into one formatted daily P&L + ad-performance spreadsheet — no manual copy-paste between platforms.

Это демонстрация, собранная по публичной документации Shopify Admin API и Meta Marketing API — не то, что работало на реальном бизнесе. Это clean-room пример: реальные эндпоинты, реальная аутентификация, реальная пагинация, реальная обработка ошибок, написанные с нуля, чтобы показать, как именно строится такая автоматизация. Он работает end-to-end в mock-режиме без учётных данных (реалистичные фикстурные данные вместо живых ответов) и переключается в live-режим для каждой интеграции, как только задаются реальные учётные данные — см. Как запустить.

Клиент Shopify запускался в live-режиме против реального магазина для разработки Shopify Partners (песочницы, а не производственного бизнеса) — реальная аутентификация, реальный заказ, реальные ответы API. В ходе этого процесса всплыли и были исправлены два реальных крайних случая с nullable-значениями (см. Известные упрощения), которые одни только mock-фикстуры не покрывали. Meta Ads в этом репозитории по умолчанию работает через mock-транспорт; код клиента написан так же и переключается на live, как только заданы 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, который оборачивает весь рабочий процесс в триггер на естественном языке («запусти ежедневный отчёт»)

• Включает готовый пример вывода, так что результат виден без запуска чего-либо

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 эндпоинтов, реальные заголовки аутентификации, реальные циклы пагинации, реальный backoff для 429. Единственное, что меняется между mock- и live-режимом, — это HTTP-транспорт (clients/http.py):

• Live: httpx.AsyncClient открывает реальное соединение с Shopify / Meta.

• Mock: httpx.AsyncClient получает httpx.ASGITransport, указывающий на внутрипроцессное FastAPI-приложение (fixtures/mock_api.py), отдающее реалистичные фикстурные данные. Порт не занимается, подпроцесс не запускается — но запросы по-прежнему проходят через настоящую HTTP/ASGI-маршрутизацию, заголовки и JSON-кодирование.

Это означает, что код клиента, который читает ревьюер, — это тот же код, который выполнялся бы против живого магазина, а не 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-режим независимо, как только появляются её собственные учётные данные, так что вы можете запустить Shopify в live, а Meta оставить в mock-режиме (или наоборот):

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 не увидит активированное виртуальное окружение:

{
  "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"
    }
  }
}

Затем спрашивайте Клода что-то вроде «какой сегодня P&L у Shopify?» или «покажи мне вчерашнюю эффективность Meta Ads» — он вызовет инструменты напрямую, по умолчанию в mock-режиме.

Как навык

skills/daily-report/SKILL.md оборачивает процесс генерации отчёта, чтобы Claude Code запускал его по триггеру на естественном языке («запусти ежедневный отчёт»), а не по точной команде CLI. Путь полного отчёта вообще не нуждается в MCP-конфиге выше — он напрямую запускает daily_report.py, который вызывает клиенты как обычный Python, без участия MCP. MCP-конфиг нужен только для другого пути навыка: ответа на разовый вопрос по одной метрике («какой сегодня ROAS?») через вызов get_daily_pnl / get_daily_ad_performance как MCP-инструментов вместо запуска полного отчёта.

Структура проекта

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 использует поле InventoryItem.cost в Shopify через настоящий двухэтапный поиск (вариант → inventory_item_id → пакетное получение inventory_items) — Shopify не отдаёт себестоимость напрямую в позиции заказа. И cost, и sku позиции заказа могут быть nullable в живом магазине (торговец мог их никогда не задавать) — это обнаружено при live-тестировании на реальном dev-магазине, а не только по документации. Оба случая обрабатываются как нулевая себестоимость / отсутствующий SKU, а не как ошибка.

• Возвращённые заказы полностью исключаются из выручки/COGS/количества заказов в daily_pnl(). Учёт частичных возвратов и возвратов товаров потребовал бы ресурса Refund — это вне рамок данного примера.

• Атрибуция покупок в Meta использует тип действия purchase из массивов actions/action_values в том окне атрибуции, которое настроено для рекламного аккаунта, — этот клиент его не переопределяет.

• Агент отчётности в настоящее время забирает все доступные заказы/инсайты, а не фильтрует по диапазону дат; в продакшене ежедневный cron передавал бы created_at_min/time_range за целевой день.

Лицензия

MIT — см. LICENSE.