# Shopify MCP Server

[![Tests](https://img.shields.io/github/actions/workflow/status/aserper/shopify-mcp/test.yml?style=for-the-badge&label=tests)](https://github.com/aserper/shopify-mcp/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=for-the-badge)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/ghcr.io-aserper%2Fshopify--mcp-blue?style=for-the-badge)](https://ghcr.io/aserper/shopify-mcp)

![GitHub stars](https://img.shields.io/github/stars/aserper/shopify-mcp?style=social)
![GitHub forks](https://img.shields.io/github/forks/aserper/shopify-mcp?style=social)

A Model Context Protocol (MCP) server that provides full access to the Shopify Admin GraphQL API. Covers the complete merchant experience with **75 tools** spanning products, orders, customers, inventory, collections, discounts, analytics, fulfillment, and more.

## Features

- **Full Shopify Admin API coverage** — 75 MCP tools matching the Shopify mobile app's capabilities
- **Dual authentication** — Static access token for quick setup, OAuth client credentials for production
- **GraphQL Admin API** — Uses Shopify's modern GraphQL API (2026-01 version)
- **Cost-aware rate limiting** — Tracks Shopify's throttle bucket and backs off automatically
- **ShopifyQL analytics** — Sales, orders, inventory, financial, and top products reports
- **TypeScript** — Full type safety with strict mode

| Category | Tools |
|----------|-------|
| **Products** | `list-products`, `get-product`, `create-product`, `update-product`, `delete-product`, `search-products`, `list-product-variants`, `create-product-variant`, `update-product-variant`, `delete-product-variant`, `manage-product-options`, `manage-product-images` |
| **Orders** | `list-orders`, `get-order`, `cancel-order`, `close-order`, `reopen-order`, `update-tracking`, `create-refund`, `calculate-refund`, `list-order-risks`, `add-order-note`, `list-order-transactions` |
| **Customers** | `list-customers`, `get-customer`, `create-customer`, `update-customer`, `delete-customer`, `search-customers`, `merge-customers`, `manage-customer-addresses` |
| **Discounts** | `list-discount-codes`, `create-discount-code`, `update-discount-code`, `delete-discount-code`, `create-automatic-discount`, `delete-automatic-discount` |
| **Inventory** | `list-inventory-levels`, `adjust-inventory`, `set-inventory`, `list-inventory-items`, `move-inventory` |
| **Collections** | `list-collections`, `get-collection`, `create-collection`, `update-collection`, `manage-collection-products` |
| **Draft Orders** | `list-draft-orders`, `get-draft-order`, `create-draft-order`, `update-draft-order`, `complete-draft-order` |
| **Analytics** | `get-sales-report`, `get-orders-report`, `get-inventory-report`, `get-financial-summary`, `get-top-products` |
| **Shop** | `get-shop-info`, `list-shop-policies`, `list-payment-settings`, `list-currencies` |
| **Metafields** | `list-metafields`, `get-metafield`, `set-metafield`, `delete-metafield` |
| **Fulfillment** | `list-fulfillment-orders`, `create-fulfillment`, `cancel-fulfillment`, `list-fulfillment-services` |
| **Locations** | `list-locations`, `get-location`, `list-location-inventory` |
| **Marketing** | `list-marketing-events`, `create-marketing-event`, `get-marketing-activity` |

## Installation

### From source

```bash
git clone https://github.com/aserper/shopify-mcp.git
cd shopify-mcp
npm install
npm run build
```

### Docker

```bash
docker pull ghcr.io/aserper/shopify-mcp:latest
```

## Configuration

Create a Custom App in Shopify Admin → Settings → Apps and sales channels → Develop apps, or register an app in the [Shopify Partners Dashboard](https://partners.shopify.com/).

| Variable | Required | Description |
|----------|----------|-------------|
| `SHOPIFY_STORE_DOMAIN` | Yes | Your store domain (e.g. `my-store.myshopify.com`) |
| `SHOPIFY_ACCESS_TOKEN` | Option 1 | Admin API access token from a Custom App |
| `SHOPIFY_CLIENT_ID` | Option 2 | OAuth client ID from Partners Dashboard |
| `SHOPIFY_CLIENT_SECRET` | Option 2 | OAuth client secret from Partners Dashboard |
| `SHOPIFY_API_VERSION` | No (default: `2026-01`) | Shopify API version |

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

## Usage

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "shopify": {
      "command": "node",
      "args": ["/path/to/shopify-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "my-store.myshopify.com",
        "SHOPIFY_ACCESS_TOKEN": "shpat_xxxxx"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add shopify-mcp \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
  -e SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  -- node /path/to/shopify-mcp/dist/index.js
```

### Docker

```bash
docker run --rm \
  -e SHOPIFY_STORE_DOMAIN=my-store.myshopify.com \
  -e SHOPIFY_ACCESS_TOKEN=shpat_xxxxx \
  ghcr.io/aserper/shopify-mcp:latest
```

## Authentication

**Static Token** — Generate an Admin API access token from a Custom App in your Shopify admin. Simplest setup, token doesn't expire unless revoked.

**OAuth Client Credentials** — Create an app in the Shopify Partners Dashboard. The server exchanges your client ID and secret for an access token automatically at startup.

## Development

```bash
npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run tests
npm run dev          # Watch mode
npm run lint         # Type check
```

## Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Shopify Inc. It is an independent, open-source tool that interacts with Shopify's publicly available APIs. "Shopify" is a registered trademark of Shopify Inc.

## License

MIT