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

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

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

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

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

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

📊 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.

# 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