---
AIGC:
    Label: "1"
    ContentProducer: 001191440300708461136T1XGW3
    ProduceID: a60f8e46820ea466ef0868a20e79d739_6fc44ac2d27f11f196c5525400248c00
    ReservedCode1: Ms0XkeFrR7dbnIUJDH7Za5ErwbcaOgxsDCu7djCtv5/ImJ0CLsCcutypQRUaR9Jje3M7wrn05kZ/3fpjC+TDxc44qLdP2G+oc9ciNFxXW5eK42wyCXNXF1ywPniW72FazYkwVBmTTv+ZWf5w3iZVQTEmJHUCWZXNeVFkEDS2Kndl6IoPHbC7SS1FU0g=
    ContentPropagator: 001191440300708461136T1XGW3
    PropagateID: a60f8e46820ea466ef0868a20e79d739_6fc44ac2d27f11f196c5525400248c00
    ReservedCode2: Ms0XkeFrR7dbnIUJDH7Za5ErwbcaOgxsDCu7djCtv5/ImJ0CLsCcutypQRUaR9Jje3M7wrn05kZ/3fpjC+TDxc44qLdP2G+oc9ciNFxXW5eK42wyCXNXF1ywPniW72FazYkwVBmTTv+ZWf5w3iZVQTEmJHUCWZXNeVFkEDS2Kndl6IoPHbC7SS1FU0g=
---

# Shopify Growth MCP — AI Store Operations, SEO & Analytics

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-20%2B-brightgreen)](package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
[![Tools](https://img.shields.io/badge/tools-61-blue)](docs/tools.md)
[![Tests](https://img.shields.io/badge/tests-64%20passing-brightgreen)](tests)
[![CI](https://img.shields.io/badge/CI-GitHub%20Actions-2088FF)](.github/workflows/ci.yml)

A **production-grade Model Context Protocol (MCP) server for Shopify** that lets AI assistants like **Claude, Cursor, ChatGPT, VS Code and Codex** operate your store through natural language — while giving merchants, agencies and SEO professionals actionable growth workflows built on real store data.

**Stop juggling 20 tabs in Shopify Admin. Ask your AI assistant to find low-stock products, audit SEO metadata, summarize sales trends, or draft marketing copy — and get structured, safe, reviewable results.**

- **61 MCP tools** across products, orders, customers, collections, inventory, metafields, tags, SEO, GEO, analytics, feeds and marketing.
- **Read-only by default**, with plan previews, bound approvals and audit logging for every write.
- **Runs with zero configuration** in demo mode (fictional store data) — no Shopify credentials required to explore.
- **Deterministic core**: Shopify connectivity and analytics never require an LLM API key.

---

## Why Shopify Growth MCP?

Most Shopify MCP servers are thin API wrappers: they expose a CRUD surface but don't help you *decide* what to do next. Shopify Growth MCP combines reliable store operations with a growth layer that turns raw Shopify data into prioritized, explainable recommendations:

| Problem merchants face | What this server does |
| --- | --- |
| Products missing titles, descriptions or alt text | `seo_audit` finds gaps with severity + evidence + suggested fix |
| Low stock and stale listings cause lost sales | `inventory_intelligence` flags thresholds, stale products and reorder priorities |
| Hard to see how the store is actually performing | `analytics_summary` computes sales, AOV, best sellers and trends from real orders |
| Feed data quality breaks ad campaigns | `feed_quality_audit` + `feed_export` validate and export product feeds |
| AI search engines can't understand the store | `geo_ai_readiness` audits content clarity, structured data and machine readability |
| Writes are risky | Plan → preview → bound approval → apply, with a full audit trail |

---

## Feature Highlights

### Core store operations (61 tools)

- **Products** — list, search, create, update, archive, delete, media, variants, metafields, tags.
- **Orders** — list, get, update, cancel, draft orders, customer order history.
- **Customers** — list, search, get, create, update, addresses, order summaries (privacy-minimized).
- **Collections** — list, get, create, update, membership management, uncategorized-product detection.
- **Inventory** — levels, locations, set quantities, low-stock alerts.
- **Metafields & tags** — list, set, delete, add/remove tags with namespace/key validation.

### Growth differentiators

- **SEO audit** (`seo_audit`) — scans products and collections for missing titles, weak descriptions, duplicate content, missing alt text, metadata gaps; returns severity, evidence and estimated effort.
- **AI-assisted SEO proposals** (`seo_proposals`, `seo_proposals_apply`) — generates reviewable title/description/metadata proposals in bulk; optional LLM provider for richer drafts (template fallback included).
- **GEO / AI-search readiness** (`geo_ai_readiness`) — evidence-based audit of content clarity, naming consistency, structured data and machine readability. No ranking guarantees, ever.
- **Store analytics** (`analytics_*`) — sales totals, order counts, AOV, best sellers, sales trends, discounts, refunds, inventory exposure, product comparisons. Deterministic formulas documented.
- **Product feed quality** (`feed_quality_audit`, `feed_export`) — validates data against marketing-readiness criteria and exports structured feeds.
- **Inventory intelligence** (`inventory_intelligence`) — configurable low-stock thresholds, stale-product detection, reorder suggestions, variant inconsistencies.
- **Marketing preparation** (`marketing_*`) — ad copy drafts, campaign briefs, campaign naming, product grouping by category/priority.

### Safety first

- **Read-only by default**: every tool declares a risk tier (`READ` / `WRITE` / `DESTRUCTIVE`).
- **Plan-and-apply workflow**: bulk writes produce a preview (IDs, current values, proposed values, affected counts, warnings); an approval token is bound to the exact plan hash — changed parameters require a new approval.
- **Audit logging**: every operation is recorded with redacted secrets.
- **Least-privilege guidance**: setup docs show the minimal Admin API scopes.
- **No silent writes, no fabricated results, no fake "approved by Google/Meta" claims.**

---

## Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│  MCP clients: Claude Desktop · Claude Code · Cursor · VS Code · Codex │
└──────────────────────────────────────────┬───────────────────────────┘
                                           │ Model Context Protocol (stdio)
┌──────────────────────────────────────────▼───────────────────────────┐
│                       shopify-growth-mcp (this repo)                 │
│  ┌───────────────┐  ┌──────────────┐  ┌───────────────────────────┐  │
│  │ Tool registry │  │ Policy engine│  │ Audit log / approvals     │  │
│  │ 61 tools      │  │ READ/WRITE/  │  │ previews, bound tokens,   │  │
│  │ risk-tiered   │  │ DESTRUCTIVE  │  │ redaction                 │  │
│  └──────┬────────┘  └──────┬───────┘  └───────────────────────────┘  │
│         │                  │                                         │
│  ┌──────▼──────────────────▼──────────────────────────────────────┐  │
│  │ Shopify GraphQL client: pagination · retries · rate limits ·   │  │
│  │ timeouts · cost awareness · API version pinning (2025-10)      │  │
│  └──────────────────────────────┬────────────────────────────────┘  │
└─────────────────────────────────┼───────────────────────────────────┘
                                  │ Shopify Admin GraphQL API
                        ┌─────────▼─────────┐
                        │  Your Shopify store│
                        └───────────────────┘
```

Modules: `src/server` (lifecycle/transport) · `src/tools` (registry) · `src/shopify` (GraphQL client, operations, pagination) · `src/auth` (token lifecycle) · `src/security` (policy, approvals, previews, audit, redaction) · `src/seo` (audits, GEO, proposals, feed quality) · `src/analytics` (metrics) · `src/workflows` (inventory intelligence, marketing, store ops, plan) · `src/demo` (fictional demo data) · `src/config` (env validation) · `src/errors` (normalized errors) · `src/utils`.

See [docs/architecture.md](docs/architecture.md) for the full design, data-flow and decision log.

---

## Quick Start

### Prerequisites

- Node.js **22.12+** (tested on Node 24).
- No Shopify account required for demo mode.

### 30-second demo (no credentials)

```bash
git clone https://github.com/hamid-digitalmarketer/shopify-growth-mcp.git
cd shopify-growth-mcp
npm install
npm run build
npx shopify-growth-mcp --demo
```

The server starts in **demo mode** against clearly-labeled fictional store data. Point any MCP client at it (see [docs/client-configuration.md](docs/client-configuration.md)) and ask:

> "Run a store health check, then show me the top 5 best-selling products and any products with low stock."

Demo data is synthetic and always labeled `demo: true` — it is **never** silently substituted for a real connection.

### Connect a real Shopify store

1. Create a custom app in Shopify Admin → **Settings → Apps and sales channels → Develop apps**.
2. Grant the **minimum scopes** you need (e.g. `read_products`, `write_products`, `read_orders`, `read_customers`, `read_inventory`).
3. Install the app and copy the Admin API access token.
4. Configure:

```bash
cp .env.example .env
# Edit .env:
SHOPIFY_SHOP_DOMAIN=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxx
```

5. Start:

```bash
npx shopify-growth-mcp
```

Run `npx shopify-growth-mcp --help` for all options. See [docs/setup.md](docs/setup.md) and [docs/troubleshooting.md](docs/troubleshooting.md) for details.

---

## MCP Client Configuration

### Claude Desktop

```json
{
  "mcpServers": {
    "shopify-growth-mcp": {
      "command": "npx",
      "args": ["shopify-growth-mcp", "--demo"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add shopify-growth-mcp -- npx shopify-growth-mcp --demo
```

### Cursor

```json
{
  "mcpServers": {
    "shopify-growth-mcp": {
      "command": "npx",
      "args": ["shopify-growth-mcp", "--demo"]
    }
  }
}
```

See [docs/client-configuration.md](docs/client-configuration.md) for VS Code, Codex, environment overrides and live-mode examples.

---

## Tool Reference

| Category | Tools |
| --- | --- |
| Store | `get_store_info`, `health_check`, `list_tools` |
| Products | `product_list`, `product_search`, `product_get`, `product_create`, `product_update`, `product_archive`, `product_delete`, `product_media`, `product_metafields`, `product_metafield_set`, `product_metafield_delete`, `variant_create`, `variant_update`, `variant_delete` |
| Orders | `order_list`, `order_get`, `order_update`, `order_cancel`, `order_draft_create` |
| Customers | `customer_list`, `customer_search`, `customer_get`, `customer_create`, `customer_update`, `customer_orders` |
| Collections | `collection_list`, `collection_get`, `collection_create`, `collection_update`, `collection_products_add`, `collection_products_remove`, `collection_recommendations`, `collection_uncategorized_products` |
| Inventory | `inventory_levels`, `inventory_locations`, `inventory_set_quantities`, `inventory_intelligence` |
| Metafields/Tags | `metafield_list`, `metafield_set`, `metafield_delete`, `tags_add`, `tags_remove` |
| SEO / GEO | `seo_audit`, `seo_proposals`, `seo_proposals_apply`, `geo_ai_readiness` |
| Analytics | `analytics_summary`, `analytics_sales_trend`, `analytics_best_sellers`, `analytics_discounts`, `analytics_inventory_exposure`, `analytics_performance` |
| Feeds | `feed_quality_audit`, `feed_export` |
| Marketing | `marketing_ad_copy`, `marketing_campaign_brief`, `marketing_campaign_names`, `marketing_group_products` |

Full schemas, risk tiers and examples: [docs/tools.md](docs/tools.md).

---

## Security Model

- **Risk tiers**: every tool declares `READ`, `WRITE` or `DESTRUCTIVE`. Handlers consult a policy map and block unauthorized operations.
- **Plan-and-apply**: `preview=true` returns current vs proposed values and affected counts; applying requires an approval token bound to the plan hash.
- **Destructive gates**: destructive tools (e.g. `product_delete`, `order_cancel`) always require explicit confirmation — never silently executed.
- **Audit trail**: operations are recorded in `.audit/` with secret redaction.
- **Secret handling**: credentials come from environment only; logs, errors and responses are redacted. See [SECURITY.md](SECURITY.md) and [docs/threat-model.md](docs/threat-model.md).

---

## Testing & Development

```bash
npm install
npm run typecheck    # strict TypeScript check
npm run lint         # ESLint
npm test             # 64 unit + integration tests (Vitest)
npm run build        # compile to dist/
```

CI runs typecheck, lint, tests and build on every push: [.github/workflows/ci.yml](.github/workflows/ci.yml).

---

## Competitive Landscape (verified 2026-10-26)

Honest positioning against the ecosystem we studied:

| Project | Focus | Notes |
| --- | --- | --- |
| **GeLi2001/shopify-mcp** (237★) | General Admin CRUD, ~31 tools | Popular baseline; primarily API operations |
| **ShopManager AI** (shopmanagerai/shopify-mcp) | 122 read-only tools, themes/Liquid/diagnostics | Strong read-only diagnostics; no writes by design |
| **callobuzz/cob-shopify-mcp** | 49+ tools, YAML-extensible, dual auth/transport | Production-oriented DX |
| **Shopify Growth MCP (this repo)** | Store ops + SEO/GEO + analytics + inventory intelligence + marketing prep, safe writes | Growth layer on real data with plan-and-apply safety |

We are **not** claiming superiority in tool count or features — we focus on **practical growth outcomes** (SEO audits, analytics, inventory intelligence, feed quality) with a safety-first write path. Verify everything yourself: the code, tests and research notes are all in this repository.

---

## Roadmap

See [research/roadmap.md](research/roadmap.md). Near-term priorities:

1. Google Search Console integration for indexability evidence.
2. Google Analytics 4 + Google Ads / Meta Ads connectors (authorized APIs only).
3. Scheduled audits and report exports (client-ready deliverables for agencies).
4. Streamable HTTP transport for remote deployments.
5. Web dashboard for visual reports.

---

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or PR. This project follows a safety-first review process: new write tools must include policy tiers, tests and documentation.

---

## License

MIT — see [LICENSE](LICENSE).

## Recommended GitHub Topics

`shopify`, `mcp`, `mcp-server`, `model-context-protocol`, `shopify-api`, `ecommerce`, `seo`, `geo`, `ai`, `llm`, `graphql`, `claude`, `cursor`, `typescript`, `analytics`, `inventory`, `digital-marketing`

---

*Built with real store outcomes in mind: SEO audits, actionable analytics, inventory intelligence and safe automation — no fabricated features, no fake metrics.*
*（内容由AI生成，仅供参考）*