npm package: @plugix/mcp-shopify
Description: MCP Server for Shopify - Products, Orders, Inventory management
Author: Plugix
Latest version: 0.1.0

# @plugix/mcp-shopify

MCP server for Shopify store management - products, orders, customers, and inventory.

## Features

- **get_products** - List products with filters (status, vendor, type, search)
- **get_orders** - List orders with filters (status, financial, fulfillment, dates)
- **get_customers** - List customers with filters (email, search, dates)
- **get_inventory** - Get inventory levels by location
- **update_product** - Update product details (with confirmation)
- **create_product** - Create new product (with confirmation)
- **update_inventory** - Update stock levels (with confirmation)
- **get_analytics** - Shop analytics and sales metrics

## Installation

```bash
npm install @plugix/mcp-shopify
```

Or run directly:

```bash
npx @plugix/mcp-shopify
```

## Configuration

Set environment variables:

```env
# Plugix API connection
API_URL=wss://api.plugix.ai
API_TOKEN=plx_live_your_token_here

# Shopify credentials
SHOPIFY_SHOP_DOMAIN=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_VERSION=2024-01  # Optional, defaults to 2024-01
```

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Docker

```bash
docker build -t plugix-mcp-shopify .
docker run --env-file .env plugix-mcp-shopify
```

### Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "shopify": {
      "command": "npx",
      "args": ["@plugix/mcp-shopify"],
      "env": {
        "API_URL": "wss://api.plugix.ai",
        "API_TOKEN": "plx_live_your_token",
        "SHOPIFY_SHOP_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxx"
      }
    }
  }
}
```

## Tools Reference

### get_products

List products from your Shopify store.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| status | string | Filter: active, archived, draft |
| vendor | string | Filter by vendor name |
| productType | string | Filter by product type |
| search | string | Search by product title |
| limit | number | Max results (default: 20, max: 250) |

**Example:**

```json
{
  "name": "get_products",
  "arguments": {
    "status": "active",
    "vendor": "Nike",
    "limit": 10
  }
}
```

### get_orders

List orders from your Shopify store.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| status | string | open, closed, cancelled, any |
| financialStatus | string | authorized, pending, paid, refunded, etc. |
| fulfillmentStatus | string | shipped, partial, unshipped, unfulfilled |
| createdAtMin | string | ISO 8601 date (orders after) |
| createdAtMax | string | ISO 8601 date (orders before) |
| limit | number | Max results (default: 20, max: 250) |

**Example:**

```json
{
  "name": "get_orders",
  "arguments": {
    "status": "open",
    "fulfillmentStatus": "unfulfilled",
    "limit": 20
  }
}
```

### get_customers

List customers from your Shopify store.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| email | string | Filter by exact email |
| search | string | Search by name or email |
| createdAtMin | string | ISO 8601 date |
| createdAtMax | string | ISO 8601 date |
| limit | number | Max results (default: 20, max: 250) |

**Example:**

```json
{
  "name": "get_customers",
  "arguments": {
    "search": "john",
    "limit": 10
  }
}
```

### get_inventory

Get inventory levels for products.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| inventoryItemIds | array | List of inventory item IDs |
| locationIds | array | Filter by location IDs |
| limit | number | Max results (default: 50, max: 250) |

**Example:**

```json
{
  "name": "get_inventory",
  "arguments": {
    "inventoryItemIds": ["12345678901234", "12345678901235"]
  }
}
```

### update_product

Update an existing product. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| productId | string | Yes | Product ID to update |
| title | string | No | New title |
| description | string | No | New description (HTML) |
| vendor | string | No | New vendor |
| productType | string | No | New product type |
| tags | array | No | New tags list |
| status | string | No | active, archived, draft |
| confirmed | boolean | Yes | Must be `true` to save |

**Example:**

```json
{
  "name": "update_product",
  "arguments": {
    "productId": "1234567890",
    "title": "Updated Product Name",
    "status": "active",
    "confirmed": true
  }
}
```

### create_product

Create a new product. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | Yes | Product title |
| description | string | No | Product description (HTML) |
| vendor | string | No | Vendor name |
| productType | string | No | Product type |
| tags | array | No | Product tags |
| status | string | No | Status (default: draft) |
| price | string | No | Price (e.g., "19.99") |
| sku | string | No | SKU code |
| confirmed | boolean | Yes | Must be `true` to create |

**Example:**

```json
{
  "name": "create_product",
  "arguments": {
    "title": "New Product",
    "description": "<p>Product description</p>",
    "price": "29.99",
    "sku": "NEW-001",
    "confirmed": true
  }
}
```

### update_inventory

Update inventory level for a product variant. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| inventoryItemId | string | Yes | Inventory item ID (from variant) |
| locationId | string | Yes | Location ID |
| available | number | Yes | New quantity |
| confirmed | boolean | Yes | Must be `true` to update |

**Example:**

```json
{
  "name": "update_inventory",
  "arguments": {
    "inventoryItemId": "12345678901234",
    "locationId": "9876543210",
    "available": 100,
    "confirmed": true
  }
}
```

### get_analytics

Get shop analytics and sales metrics.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| startDate | string | Start of period (ISO 8601, default: 30 days ago) |
| endDate | string | End of period (ISO 8601, default: now) |

**Returns:**
- Total orders
- Total revenue
- Average order value
- Total customers
- Top selling products
- Orders by status

**Example:**

```json
{
  "name": "get_analytics",
  "arguments": {
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z"
  }
}
```

## Shopify Access Token

To get a Shopify Admin API access token:

1. Go to your Shopify admin panel
2. Navigate to **Settings** > **Apps and sales channels**
3. Click **Develop apps** (enable if needed)
4. Create a new app
5. Configure Admin API scopes:
   - `read_products`, `write_products`
   - `read_orders`
   - `read_customers`
   - `read_inventory`, `write_inventory`
   - `read_locations`
6. Install the app and copy the Admin API access token

## Required Scopes

Minimum required Admin API scopes:

| Scope | Purpose |
|-------|---------|
| `read_products` | List and view products |
| `write_products` | Create and update products |
| `read_orders` | List and view orders |
| `read_customers` | List and view customers |
| `read_inventory` | View inventory levels |
| `write_inventory` | Update inventory levels |
| `read_locations` | View store locations |

## Testing

```bash
npm test
```

## Troubleshooting

### Connection refused
- Check `API_URL` is correct
- Verify `API_TOKEN` is valid
- Ensure firewall allows outbound WebSocket

### Shopify API errors
- Verify `SHOPIFY_SHOP_DOMAIN` format (e.g., `store.myshopify.com`)
- Check `SHOPIFY_ACCESS_TOKEN` is valid
- Ensure required scopes are enabled

### Rate limiting
- Shopify has API rate limits
- The connector handles pagination automatically
- For large operations, use smaller batch sizes

## License

MIT