npm package: @plugix/mcp-woocommerce
Description: MCP Server for WooCommerce - Products, Orders, WordPress integration
Author: Plugix
Latest version: 0.1.0

# @plugix/mcp-woocommerce

MCP server for WooCommerce store management and e-commerce operations.

## Features

- **get_products** - List products with filters (category, status, stock)
- **get_orders** - List orders with filters (status, customer, date range)
- **get_customers** - List customers with search and filters
- **get_categories** - List product categories
- **update_product** - Update product details (with confirmation)
- **create_product** - Create new products (with confirmation)
- **update_stock** - Update stock levels (with confirmation)
- **get_reports** - Sales and top sellers reports

## Installation

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

Or run directly:

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

## Configuration

Set environment variables:

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

# WooCommerce credentials
WOOCOMMERCE_URL=https://your-store.com
WOOCOMMERCE_CONSUMER_KEY=ck_your_consumer_key
WOOCOMMERCE_CONSUMER_SECRET=cs_your_consumer_secret

# Optional
INSTANCE_ID=my-store-1
INSTANCE_NAME=My WooCommerce Store
```

### Getting WooCommerce API Keys

1. In WordPress admin, go to **WooCommerce > Settings > Advanced > REST API**
2. Click **Add key**
3. Set **Description** (e.g., "Plugix MCP Server")
4. Set **User** (admin user recommended)
5. Set **Permissions** to **Read/Write**
6. Click **Generate API key**
7. Copy the **Consumer key** and **Consumer secret**

## Usage

### Development

```bash
npm run dev
```

### Production

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

### Docker

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

### Claude Desktop Integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "woocommerce": {
      "command": "npx",
      "args": ["@plugix/mcp-woocommerce"],
      "env": {
        "API_URL": "wss://api.plugix.ai",
        "API_TOKEN": "plx_live_your_token",
        "WOOCOMMERCE_URL": "https://your-store.com",
        "WOOCOMMERCE_CONSUMER_KEY": "ck_xxx",
        "WOOCOMMERCE_CONSUMER_SECRET": "cs_xxx"
      }
    }
  }
}
```

## Tools Reference

### get_products

List products with optional filters.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| category | number | Filter by category ID |
| search | string | Search term for product name or SKU |
| status | string | Filter: draft, pending, private, publish |
| stock_status | string | Filter: instock, outofstock, onbackorder |
| per_page | number | Products per page (default: 20, max: 100) |
| page | number | Page number (default: 1) |

**Example:**

```json
{
  "name": "get_products",
  "arguments": {
    "status": "publish",
    "stock_status": "instock",
    "per_page": 50
  }
}
```

### get_orders

List orders with optional filters.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| status | string | Filter: pending, processing, on-hold, completed, cancelled, refunded, failed |
| customer | number | Filter by customer ID |
| after | string | Orders after this date (ISO 8601) |
| before | string | Orders before this date (ISO 8601) |
| per_page | number | Orders per page (default: 20, max: 100) |
| page | number | Page number (default: 1) |

**Example:**

```json
{
  "name": "get_orders",
  "arguments": {
    "status": "processing",
    "after": "2024-01-01T00:00:00Z"
  }
}
```

### get_customers

List customers with optional filters.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| search | string | Search by name or username |
| email | string | Filter by exact email |
| per_page | number | Customers per page (default: 20, max: 100) |
| page | number | Page number (default: 1) |

### get_categories

List product categories.

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| parent | number | Filter by parent ID (0 for top-level) |
| hide_empty | boolean | Hide categories with no products |
| per_page | number | Categories per page (default: 100) |

### update_product

Update an existing product. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | number | Yes | Product ID |
| name | string | No | New product name |
| description | string | No | New description (HTML allowed) |
| short_description | string | No | New short description |
| regular_price | string | No | New regular price |
| sale_price | string | No | New sale price |
| status | string | No | Product status |
| confirmed | boolean | Yes | Must be `true` to update |

**Example:**

```json
{
  "name": "update_product",
  "arguments": {
    "id": 123,
    "description": "<p>Updated product description</p>",
    "regular_price": "29.99",
    "confirmed": true
  }
}
```

### create_product

Create a new product. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | Yes | Product name |
| type | string | No | simple, variable, grouped, external (default: simple) |
| sku | string | No | Product SKU |
| regular_price | string | No | Regular price |
| description | string | No | Description (HTML allowed) |
| short_description | string | No | Short description |
| categories | array | No | Array of category objects: `[{"id": 1}]` |
| status | string | No | Status (default: draft) |
| confirmed | boolean | Yes | Must be `true` to create |

**Example:**

```json
{
  "name": "create_product",
  "arguments": {
    "name": "New Product",
    "regular_price": "49.99",
    "description": "<p>Product description here</p>",
    "categories": [{"id": 15}],
    "confirmed": true
  }
}
```

### update_stock

Update product stock quantity. Requires confirmation.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | number | Yes | Product ID |
| stock_quantity | number | Yes | New stock quantity |
| stock_status | string | No | instock, outofstock, onbackorder |
| confirmed | boolean | Yes | Must be `true` to update |

**Example:**

```json
{
  "name": "update_stock",
  "arguments": {
    "id": 123,
    "stock_quantity": 50,
    "confirmed": true
  }
}
```

### get_reports

Get sales reports and analytics.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| type | string | Yes | Report type: sales, top_sellers |
| period | string | No | week, month, last_month, year |
| date_min | string | No | Start date (YYYY-MM-DD) |
| date_max | string | No | End date (YYYY-MM-DD) |

**Example:**

```json
{
  "name": "get_reports",
  "arguments": {
    "type": "sales",
    "period": "month"
  }
}
```

## WooCommerce API Permissions

The API keys need the following permissions:

- **Products**: Read/Write (for get_products, update_product, create_product, update_stock)
- **Orders**: Read (for get_orders)
- **Customers**: Read (for get_customers)
- **Reports**: Read (for get_reports)

For read-only access, create keys with **Read** permission only.

## Testing

```bash
npm test
```

## License

MIT