@ainative/commerce-mcp

MCP server for ZeroCommerce -- manage products, orders, customers, analytics, and storefronts through any MCP-compatible AI client.

46 tools across 6 categories, mirroring the full ZeroCommerce REST API.

Install

npm install @ainative/commerce-mcp

Quick Start

As a library

import { ZeroCommerceMCP } from '@ainative/commerce-mcp';

const mcp = new ZeroCommerceMCP({
  apiUrl: process.env.ZEROCOMMERCE_API_URL,
  apiKey: process.env.ZEROCOMMERCE_API_KEY,
  storeSlug: 'my-store',
});

// List products
const products = await mcp.catalog.listProducts();

// Get order details
const order = await mcp.orders.getOrder('order-123');

// Revenue summary
const revenue = await mcp.analytics.getRevenueSummary(30);

// Execute any tool by name
const result = await mcp.executeTool('list_products', {
  store_slug: 'my-store',
  limit: 10,
});

As a CLI

# List available tools
npx @ainative/commerce-mcp --store my-store --list-tools

# Execute a tool
npx @ainative/commerce-mcp --store my-store --tool list_products --limit 10

# With explicit API key
npx @ainative/commerce-mcp --store my-store --api-key zc_... --tool get_revenue_summary --days 7

Claude Code / Cursor MCP config

{
  "mcpServers": {
    "commerce": {
      "command": "npx",
      "args": ["@ainative/commerce-mcp", "--store", "my-store"],
      "env": {
        "ZEROCOMMERCE_API_URL": "https://zerocommerce-production.up.railway.app",
        "ZEROCOMMERCE_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ZEROCOMMERCE_API_URL | ZeroCommerce API base URL | https://zerocommerce-production.up.railway.app | | ZEROCOMMERCE_API_KEY | API key for authentication | -- | | ZEROCOMMERCE_STORE | Default store slug | -- | | AINATIVE_API_KEY | AINative API key for ZeroMemory integration | -- |

Tool Categories

Catalog (12 tools)

| Tool | Description | |------|-------------| | list_products | List products with prices, stock, and IDs | | get_product | Get full product details by ID | | create_product | Create a new product | | update_product | Update product fields | | delete_product | Permanently delete a product | | search_products_semantic | Natural language product search | | update_stock | Set absolute stock level | | adjust_stock | Adjust stock by a relative amount | | bulk_update_prices | Update prices for multiple products | | activate_product | Make product visible in storefront | | deactivate_product | Hide product from storefront | | duplicate_product | Clone an existing product |

Orders (10 tools)

| Tool | Description | |------|-------------| | list_orders | List orders, filter by status | | get_order | Get full order details | | update_order_status | Change order status | | cancel_order | Cancel an order | | refund_order | Issue full or partial refund | | add_tracking | Add shipping tracking info | | list_orders_by_customer | Orders by customer email | | get_order_analytics | Order statistics for a period | | export_orders_csv | Export orders as CSV | | search_orders | Search orders by customer |

Customers (6 tools)

| Tool | Description | |------|-------------| | list_customers | List customers with order stats | | get_customer | Customer profile with history | | get_customer_lifetime_value | Calculate customer LTV | | search_customers | Search by name or email | | get_top_customers | Top customers by spend | | export_customers_csv | Export customer data |

Analytics (8 tools)

| Tool | Description | |------|-------------| | get_revenue_summary | Revenue, orders, AOV, top products | | get_top_products | Best sellers by revenue | | get_conversion_funnel | Cart-to-order conversion metrics | | get_revenue_by_day | Daily revenue breakdown | | get_inventory_status | Inventory health overview | | get_recent_activity | Latest store events | | get_store_health | Store health score | | compare_periods | Compare two time periods |

Storefront & Config (10 tools)

| Tool | Description | |------|-------------| | get_storefront_url | Public storefront URL | | preview_storefront | Current storefront state | | set_featured_products | Set homepage featured products | | get_inventory_alerts | Low-stock product alerts | | get_store_info | Store settings and config | | update_store_settings | Update store settings | | get_webhooks | List webhook subscriptions | | create_webhook | Register a new webhook | | delete_webhook | Remove a webhook | | get_api_keys | List API keys (masked) |

Programmatic API

import { ZeroCommerceMCP, ZeroCommerceClient, ApiError } from '@ainative/commerce-mcp';

// Use the client directly for lower-level access
const client = new ZeroCommerceClient({
  apiUrl: 'https://zerocommerce-production.up.railway.app',
  apiKey: 'your-key',
});

try {
  const data = await client.get('/api/v1/products/', {
    store_slug: 'my-store',
    limit: 5,
  });
  console.log(data);
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`API Error ${err.status}: ${err.message}`);
  }
}

License

MIT