# Shopify MCP Server

An MCP server that gives AI assistants real-time access to your Shopify store analytics through ShopifyQL and the Admin GraphQL API.

## What It Does

Connect any MCP-compatible AI assistant (Claude, GPT, Cursor, etc.) to your Shopify store. Ask questions in plain English — the server translates them into ShopifyQL queries and GraphQL calls, then returns real data from your store. Sales, orders, inventory, traffic, marketing — all queryable through conversation.

## Tools

| Tool | Description |
|------|-------------|
| `shopify_sales_summary` | Total sales, net sales, orders, AOV, returns, and discounts for any date range |
| `shopify_sales_by_product` | Revenue breakdown by product with sorting and limits |
| `shopify_sales_by_channel` | Sales split across channels (Online Store, POS, etc.) |
| `shopify_sales_over_time` | Time series sales trends by day, week, month, quarter, or year |
| `shopify_orders` | Recent orders with line items, customer info, and fulfillment status |
| `shopify_customer_metrics` | Customer acquisition and behavior — new vs. returning over time |
| `shopify_traffic` | Sessions, visitors, and conversion rate — optionally grouped by source, device, or country |
| `shopify_sales_by_geography` | Sales breakdown by billing country |
| `shopify_ad_spend` | Marketing event data from Shopify campaigns |
| `shopify_shop_campaign_insights` | Shop campaign performance — ad spend vs. sales with period comparisons |
| `shopify_inventory` | Inventory levels by variant with SKU search and low-stock filtering |
| `shopify_sales_by_discount` | Sales breakdown by discount code |
| `shopify_custom_query` | Run raw ShopifyQL for anything the pre-built tools don't cover |

## Setup

### Prerequisites

- Node.js 18+
- A Shopify store with a [custom app](https://help.shopify.com/en/manual/apps/app-types/custom-apps)

### 1. Create a Shopify Custom App

1. In your Shopify admin, go to **Settings > Apps and sales channels > Develop apps**
2. Click **Create an app** and give it a name
3. Under **Configuration**, click **Configure Admin API scopes** and enable these scopes:

| Scope | Purpose |
|-------|---------|
| `read_reports` | ShopifyQL queries (sales, traffic, campaigns) |
| `read_orders` | Order details and history |
| `read_analytics` | Session and traffic data |
| `read_products` | Product and inventory data |
| `read_customers` | Customer metrics |

4. Click **Save** and then **Install app**

### 2. Get Your Access Token

The included `get-token.js` script handles the OAuth flow:

```bash
node get-token.js <shop.myshopify.com> <client_id> <client_secret>
```

This starts a local server, opens your browser to authorize the app, and prints the access token to your terminal. Copy it — you'll need it next.

### 3. Build the Server

```bash
npm install
npm run build
```

### 4. Configure Your MCP Client

Add the server to your `.mcp.json` (or equivalent config for your AI tool):

```json
{
  "mcpServers": {
    "shopify": {
      "command": "node",
      "args": ["/path/to/shopify-mcp-server/dist/index.js"],
      "env": {
        "SHOPIFY_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx",
        "SHOPIFY_API_VERSION": "2025-10"
      }
    }
  }
}
```

Replace `/path/to/shopify-mcp-server` with the actual path to this project on your machine.

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SHOPIFY_DOMAIN` | Yes | Your `.myshopify.com` domain |
| `SHOPIFY_ACCESS_TOKEN` | Yes | Admin API access token from step 2 |
| `SHOPIFY_API_VERSION` | No | Defaults to `2025-10` |

## Usage Examples

Once configured, ask your AI assistant things like:

- **"How are sales this month compared to last month?"** — triggers `shopify_sales_summary` with comparison
- **"What are my top 10 products by revenue this quarter?"** — triggers `shopify_sales_by_product`
- **"What's my conversion rate this week, broken down by traffic source?"** — triggers `shopify_traffic` grouped by referrer
- **"Show me any products with fewer than 5 units in stock"** — triggers `shopify_inventory` with low-stock filter
- **"How much am I spending on Shop campaigns and what's the return?"** — triggers `shopify_shop_campaign_insights`

The AI picks the right tool automatically based on your question.

## License

MIT

## Built By

**Hamza Shahbaz** — Senior web developer, 13+ years building for the web.

- [hamzashahbaz.com](https://hamzashahbaz.com)
- [GitHub](https://github.com/hamzashahbaz)
- [LinkedIn](https://linkedin.com/in/hamzashahbaz)