npm package: @plugix/mcp-magento
Description: MCP Server for Magento/Adobe Commerce - Products, Orders, Catalog
Author: Plugix
Latest version: 0.1.0

# Magento/Adobe Commerce MCP Server

MCP server for Magento 2 and Adobe Commerce integration. Provides AI-powered tools for managing products, orders, customers, and inventory.

## Features

- **get_products** - Query products with filters (SKU, name, category, status, type)
- **get_categories** - List all product categories with hierarchy
- **get_orders** - Query orders with filters (status, customer, date range)
- **get_customers** - Query customers with filters (email, name, group)
- **search_products** - Search products by keyword
- **get_inventory** - Get stock levels for products
- **update_product** - Update product details (with confirmation)
- **create_product** - Create new products (with confirmation)

## Installation

```bash
npm install
cp .env.example .env
```

## Configuration

Edit `.env`:

```env
# Plugix AI Platform
API_URL=wss://api.plugix.ai
API_TOKEN=sk_live_your_token_here

# Magento credentials
MAGENTO_BASE_URL=https://your-magento.com
MAGENTO_ACCESS_TOKEN=your_magento_access_token

# Optional
INSTANCE_ID=magento-prod
INSTANCE_NAME=Magento Production
```

### Getting Magento Access Token

1. Log in to Magento Admin
2. Go to **System > Extensions > Integrations**
3. Click **Add New Integration**
4. Fill in the name (e.g., "Plugix AI")
5. Go to **API** tab and select required resources:
   - Catalog > Inventory
   - Catalog > Products
   - Sales > Orders
   - Customers
6. Save and **Activate** the integration
7. Copy the **Access Token**

## Usage

### Development

```bash
npm run dev
```

### Production

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

### Docker

```bash
docker build -t mcp-magento .
docker run --env-file .env mcp-magento
```

### NPX (Global)

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

## Tools Reference

### get_products

Query products from the Magento catalog.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| sku | string | Filter by SKU (partial match) |
| name | string | Filter by product name (partial match) |
| category_id | number | Filter by category ID |
| status | string | Filter by status: `enabled` or `disabled` |
| type | string | Filter by type: `simple`, `configurable`, `grouped`, `virtual`, `bundle`, `downloadable` |
| limit | number | Max results (default: 20, max: 100) |
| page | number | Page number (default: 1) |

**Example:**
```json
{
  "name": "get_products",
  "arguments": {
    "category_id": 3,
    "status": "enabled",
    "limit": 10
  }
}
```

### get_categories

List all product categories as a flat list with paths.

**Parameters:** None

**Returns:**
- Category ID, name, path, level
- Active status
- Product count

### get_orders

Query orders from Magento.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| status | string | Filter by status (pending, processing, complete, canceled) |
| customer_email | string | Filter by customer email |
| created_from | string | Orders created after (YYYY-MM-DD) |
| created_to | string | Orders created before (YYYY-MM-DD) |
| limit | number | Max results (default: 20, max: 100) |
| page | number | Page number (default: 1) |

**Example:**
```json
{
  "name": "get_orders",
  "arguments": {
    "status": "processing",
    "created_from": "2024-01-01",
    "limit": 50
  }
}
```

### get_customers

Query customers from Magento.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| email | string | Filter by email (partial match) |
| firstname | string | Filter by first name (partial match) |
| lastname | string | Filter by last name (partial match) |
| group_id | number | Filter by customer group ID |
| limit | number | Max results (default: 20, max: 100) |
| page | number | Page number (default: 1) |

### search_products

Search products by keyword in product name.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | Yes | Search keyword |
| limit | number | No | Max results (default: 20) |
| page | number | No | Page number (default: 1) |

### get_inventory

Get stock levels for products.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| skus | array | Array of SKUs to check. If empty, returns all products. |
| limit | number | Max results when getting all (default: 50) |
| page | number | Page number (default: 1) |

**Example:**
```json
{
  "name": "get_inventory",
  "arguments": {
    "skus": ["SKU-001", "SKU-002", "SKU-003"]
  }
}
```

### update_product

Update an existing product. Requires confirmation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| sku | string | Yes | Product SKU to update |
| name | string | No | New product name |
| price | number | No | New product price |
| status | string | No | Status: `enabled` or `disabled` |
| description | string | No | Product description (HTML) |
| short_description | string | No | Short description |
| meta_title | string | No | SEO meta title |
| meta_description | string | No | SEO meta description |
| meta_keyword | string | No | SEO keywords (comma-separated) |
| confirmed | boolean | Yes | Must be `true` to apply |

**Example:**
```json
{
  "name": "update_product",
  "arguments": {
    "sku": "PROD-001",
    "description": "Updated product description with AI-generated content...",
    "meta_title": "Product Name | Store",
    "confirmed": true
  }
}
```

### create_product

Create a new product. Requires confirmation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| sku | string | Yes | Unique product SKU |
| name | string | Yes | Product name |
| price | number | Yes | Product price |
| type | string | No | Product type (default: `simple`) |
| status | string | No | Status (default: `enabled`) |
| visibility | string | No | Visibility (default: `catalog_search`) |
| weight | number | No | Product weight |
| description | string | No | Product description |
| short_description | string | No | Short description |
| confirmed | boolean | Yes | Must be `true` to create |

**Example:**
```json
{
  "name": "create_product",
  "arguments": {
    "sku": "NEW-PROD-001",
    "name": "New Product",
    "price": 29.99,
    "type": "simple",
    "description": "AI-generated product description...",
    "confirmed": true
  }
}
```

## Magento API Requirements

Your Magento instance needs:

1. **REST API enabled** (enabled by default in Magento 2)
2. **Integration** with appropriate API permissions:
   - `Magento_Catalog::products` (read/write)
   - `Magento_Catalog::categories` (read)
   - `Magento_Sales::sales` (read)
   - `Magento_Customer::customer` (read)
   - `Magento_CatalogInventory::cataloginventory` (read)
3. **Access Token** from the integration

## Magento Versions

Tested with:
- Magento Open Source 2.4.x
- Adobe Commerce 2.4.x
- Adobe Commerce Cloud

## Testing

```bash
npm test
```

## Troubleshooting

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

### Magento API errors
- Verify `MAGENTO_BASE_URL` format (include `/rest/V1` if not auto-detected)
- Check `MAGENTO_ACCESS_TOKEN` is valid
- Verify integration has required API permissions
- Check Magento system logs

### 401 Unauthorized
- Access token may have expired
- Regenerate token in Magento Admin > System > Integrations

### Tool not found
- Restart server after tool changes
- Check tool is exported in `src/tools/index.ts`

### Rate limiting
- Magento has default rate limits
- Consider adjusting in `app/etc/env.php`

## License

MIT