Shopify Insights MCP

MCP Server for Shopify that delivers actionable business insights — comparisons, alerts, and recommendations, not just numbers.

Demo

https://github.com/user-attachments/assets/4541bf2d-8974-4944-b3cb-4b8597d071cf

Why This Exists

Existing Shopify MCP servers return raw data. Shopify Insights MCP answers "what does it mean?" and "what should I do?":

| Other MCPs | Shopify Insights MCP | |-----------|---------------------| | "You have $45,000 in sales" | "You have $45,000, 12% less than last month" | | "List of 50 products" | "5 products have critical stock and high demand" | | "10 pending orders" | "3 orders have been unfulfilled for 5+ days" |

Stack

• TypeScript + MCP SDK (@modelcontextprotocol/sdk)
• Shopify Admin API (GraphQL)
• Zod for input validation
• Transport: stdio

Installation

Option A: npm (recommended)

npm install -g shopify-insights-mcp
shopify-insights-mcp init

The init command will guide you through connecting your Shopify store and generate the Claude Desktop configuration.

Option B: From source

git clone https://github.com/VenticinqueMauro/shopify-insights-mcp.git
cd shopify-insights-mcp
npm install
npm run build
npm run setup       # Guided configuration

Shopify App Requirements

You need a Custom App with these scopes:

• read_orders, read_products, read_customers

Create one at: Shopify Admin > Settings > Apps and sales channels > Develop apps

Build & Run

npm run build       # Compile TypeScript → dist/
npm start           # Run the MCP server (stdio)
npm run setup       # Guided setup wizard
npm run inspector   # Open MCP Inspector for debugging

Usage with Claude Desktop

Quick setup (via npx)

{
  "mcpServers": {
    "shopify-insights": {
      "command": "npx",
      "args": ["-y", "shopify-insights-mcp"],
      "env": {
        "SHOPIFY_SHOP_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_your_token"
      }
    }
  }
}

Local install

{
  "mcpServers": {
    "shopify-insights": {
      "command": "node",
      "args": ["/path/to/shopify-insights-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_SHOP_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_your_token"
      }
    }
  }
}

Run shopify-insights-mcp init to generate this config automatically.

Then ask Claude things like:

• "How are sales this month compared to last month?"
• "Which products are trending up?"
• "Are there any orders that need urgent attention?"
• "How are my customers segmented?"

Configuration

Required Environment Variables

| Variable | Description | |----------|-------------| | SHOPIFY_SHOP_DOMAIN | Your store domain (e.g., my-store.myshopify.com) | | SHOPIFY_ACCESS_TOKEN | Admin API access token (starts with shpat_) |

Optional Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SHOPIFY_TIMEZONE | Auto-detected from store | IANA timezone override (e.g., America/New_York). Use when your Shopify store timezone setting is incorrect | | SHOPIFY_API_VERSION | 2025-01 | Shopify Admin API version | | SHOPIFY_MAX_RECORDS | 1000 | Maximum records fetched per tool call. Increase for large stores |

Tools (10)

Sales & Revenue

| Tool | Description | |------|-------------| | get_sales_summary | Sales summary with period-over-period comparison. Revenue, orders, AOV, units sold | | get_sales_comparison | Side-by-side comparison of two custom date ranges | | get_revenue_breakdown | Revenue broken down by product, vendor, or product type |

Products & Inventory

| Tool | Description | |------|-------------| | get_product_performance | Product ranking by revenue, units sold, or order count | | get_inventory_alerts | Stock alerts: out-of-stock, low stock, overstock detection | | get_trending_products | Trending products (rising/falling) vs. previous period |

Customers

| Tool | Description | |------|-------------| | get_customer_segments | Automatic segmentation: VIP, Loyal, Returning, New, Inactive | | get_top_customers | Customer ranking by total spend or order count |

Operations

| Tool | Description | |------|-------------| | get_order_alerts | Orders needing attention: delayed fulfillment, financial issues, high-value pending | | get_fulfillment_metrics | Operational metrics: fulfillment rate, financial status, health score |

Architecture

src/
├── index.ts                  # Entry point
├── server.ts                 # Tool registration & request handler
├── shopify/
│   ├── auth.ts               # Credentials from env vars
│   ├── client.ts             # GraphQL wrapper
│   └── queries/              # Orders, products, customers queries
├── tools/
│   ├── sales/                # 3 sales tools
│   ├── products/             # 3 product tools
│   ├── customers/            # 2 customer tools
│   └── operations/           # 2 operations tools
├── analytics/
│   ├── comparisons.ts        # Change calculation (%, direction)
│   ├── insights.ts           # Automatic insight generation
│   └── recommendations.ts    # Actionable recommendations
├── types/
│   └── shopify.ts            # Shared GraphQL types
└── utils/
    ├── dates.ts              # Period handling & date formatting
    ├── formatting.ts         # Currency, percentage, number formatting
    └── errors.ts             # Standard error handling

Example Output

📊 SALES SUMMARY - THIS MONTH

CURRENT METRICS:
• Revenue: $1,245,000.00
• Orders: 234
• Avg Order Value: $5,320.51
• Units Sold: 892

VS. PREVIOUS MONTH:
• Revenue: +18.0% (+$190,000.00)
• Orders: +12.0% (+25)
• Avg Order Value: +5.4% (+$272.00)

💡 INSIGHTS:
• 📈 Revenue grew 18.0% compared to the previous period.
• 🛒 Order volume increased 12.0% (+25 orders).

📋 RECOMMENDATIONS:
• 🚀 Leverage the positive momentum by increasing investment in top-performing channels.
• 📦 Ensure sufficient stock to sustain demand growth.

Testing

# Run unit tests
npm test

# Manual test via JSON-RPC over stdio
export $(grep -v '^#' .env | xargs)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_sales_summary","arguments":{"period":"month"}}}' | node dist/index.js

# Or use MCP Inspector
npm run inspector

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

MIT