# @thatworkagency/mcp-shopify

Model Context Protocol (MCP) server for Shopify Admin API. Provides read-only access to products, orders, customers, and shop information with multi-store support.

## Features

- **Read-only operations** — Safe for exploration and reporting
- **HTTP transport** — Remote/multi-client capable
- **Multi-store support** — Pass store credentials per-request via headers
- **GraphQL-based** — Efficient data fetching with Shopify Admin API

## Tools

| Tool | Description |
|------|-------------|
| `get_shop_info` | Get store details (name, email, domain, plan) |
| `get_products` | Fetch products with filtering and pagination |
| `get_product` | Fetch single product by ID or handle |
| `search_products` | Search products by title, SKU, or tags |
| `get_orders` | Fetch orders with filtering and pagination |
| `get_order` | Fetch single order by ID |
| `get_customers` | Fetch customers with filtering and pagination |
| `get_customer` | Fetch single customer by ID |
| `get_inventory_levels` | Fetch inventory levels for a variant |

## Installation

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

## Usage

### Start the server

```bash
npm start
# or
npm run dev
```

Server runs on `http://0.0.0.0:3000` by default. Configure with env vars:
- `PORT` — server port (default: 3000)
- `HOST` — server host (default: 0.0.0.0)

### Authentication

Pass Shopify credentials via HTTP headers on every request:

| Header | Description |
|--------|-------------|
| `x-shopify-store` | Store domain (e.g., `mystore.myshopify.com`) |
| `x-shopify-token` | Admin API access token (`shpat_xxx`) |

### Using with mcporter

```bash
# Add server to mcporter config
mcporter config add mcp-shopify \
  --url http://localhost:3000 \
  --headers '{"x-shopify-store":"mystore.myshopify.com","x-shopify-token":"shpat_xxx"}'

# List tools
mcporter list mcp-shopify --schema

# Call a tool
mcporter call mcp-shopify.get_shop_info
mcporter call mcp-shopify.get_products first=5
mcporter call mcp-shopify.search_products query="t-shirt" first=10
mcporter call mcp-shopify.get_order id="gid://shopify/Order/1234567890"
```

### Using with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "shopify": {
      "url": "http://localhost:3000",
      "headers": {
        "x-shopify-store": "mystore.myshopify.com",
        "x-shopify-token": "shpat_xxx"
      }
    }
  }
}
```

## API Examples

### Get shop info
```json
{
  "name": "get_shop_info",
  "arguments": {}
}
```

### List products
```json
{
  "name": "get_products",
  "arguments": {
    "first": 10,
    "query": "status:active"
  }
}
```

### Get product by handle
```json
{
  "name": "get_product",
  "arguments": {
    "handle": "my-product"
  }
}
```

### Search products
```json
{
  "name": "search_products",
  "arguments": {
    "query": "shirt",
    "first": 20
  }
}
```

### List orders
```json
{
  "name": "get_orders",
  "arguments": {
    "first": 5,
    "query": "status:open"
  }
}
```

### Get order
```json
{
  "name": "get_order",
  "arguments": {
    "id": "gid://shopify/Order/1234567890"
  }
}
```

### List customers
```json
{
  "name": "get_customers",
  "arguments": {
    "first": 10,
    "query": "email:john@example.com"
  }
}
```

### Get customer
```json
{
  "name": "get_customer",
  "arguments": {
    "id": "gid://shopify/Customer/9876543210"
  }
}
```

### Get inventory levels
```json
{
  "name": "get_inventory_levels",
  "arguments": {
    "variantId": "gid://shopify/ProductVariant/1111111111"
  }
}
```

## Development

```bash
# Install dependencies
npm install

# Run in dev mode with hot reload
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Start production build
npm start
```

## Docker

```bash
# Build
docker build -t mcp-shopify .

# Run
docker run -p 3000:3000 mcp-shopify
```

## License

MIT