andrei535/xcart-mcp

X-Cart MCP Server

Model Context Protocol (MCP) server for X-Cart eCommerce platform. Enables AI assistants like Claude to interact with X-Cart stores through natural language.

Features

• Full Store Management: Products, orders, customers, categories, inventory
• Role-Based Access: Admin and Sales Assistant roles with different permissions
• Automotive Support: Make/Model/Year data for automotive parts stores
• Two Transport Modes: Local (stdio) and Remote (SSE)
• Docker Ready: Packaged for Docker MCP Catalog

Quick Start

Option 1: Local Mode (stdio) - Claude Desktop

Best for personal use with Claude Desktop on your machine.

docker run -i --rm \
  -e XCART_API_URL=https://your-store.com \
  -e XCART_API_KEY=your_api_key \
  -e XCART_ROLE=admin \
  andrewkomkov/xcart-mcp

Claude Desktop Configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "xcart": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "XCART_API_URL=https://your-store.com",
        "-e", "XCART_API_KEY=your_api_key",
        "-e", "XCART_ROLE=admin",
        "andrewkomkov/xcart-mcp"
      ]
    }
  }
}

Option 2: Remote Mode (SSE) - Multi-User Access

Best for teams, third-party integrations, or shared access.

Start the server:

docker run -d --name xcart-mcp \
  -p 3000:3000 \
  -e XCART_API_URL=https://your-store.com \
  -e XCART_API_KEY=your_api_key \
  -e XCART_ROLE=admin \
  -e MCP_TRANSPORT=sse \
  -e MCP_ACCESS_TOKEN=your_secret_token \
  andrewkomkov/xcart-mcp

Client Configuration (Claude Desktop with mcp-remote):

{
  "mcpServers": {
    "xcart": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-server:3000/sse",
        "--transport", "sse-only"
      ]
    }
  }
}

SSE Endpoints:

• GET / - Server info
• GET /health - Health check
• GET /sse - SSE connection for MCP
• POST /messages?sessionId=... - Send MCP messages

Configuration

Security

Access Token Protection

When MCP_ACCESS_TOKEN is set, every tool call must include _token parameter:

{
  "name": "search_products",
  "arguments": {
    "_token": "your_secret_token",
    "query": "brake pads"
  }
}

Rate Limiting

Built-in rate limiter prevents abuse:

• Default: 60 requests per minute
• Configurable via MCP_RATE_LIMIT
• Returns error with reset time when exceeded

Best Practices

1. Always set MCP_ACCESS_TOKEN in production
2. Generate strong tokens: openssl rand -hex 32
3. Use HTTPS reverse proxy for SSE in production
4. Use different tokens for different users/roles

Roles

Admin

Full access to all store operations:

• Create, update, delete products
• Manage orders (create, update, delete, finalize)
• Customer management (full CRUD)
• Category management
• Inventory/stock management
• Coupons and discounts
• Webhooks and settings
• Analytics

Sales Assistant

Limited access for customer-facing operations:

• View products and inventory (read-only)
• Create and manage orders
• Create and update customers (no delete)
• View categories and coupons
• View analytics

Available Tools (56 total)

Products (12 tools)

search_products, get_product, get_product_by_sku, create_product, update_product, delete_product, get_product_stock, update_product_stock, get_product_images, get_product_variations, get_product_reviews, get_product_attributes

Orders (13 tools)

search_orders, get_order, get_calculated_order, create_order, update_order, get_order_items, add_order_item, update_order_item, delete_order_item, get_order_shipments, create_shipment, finalize_draft_order, get_invoices

Customers (9 tools)

search_customers, get_customer, create_customer, update_customer, delete_customer, get_customer_addresses, add_customer_address, update_customer_address, get_customer_orders

Categories (8 tools)

list_categories, get_category, create_category, update_category, delete_category, get_category_products, add_product_to_category, get_category_stats

Coupons & Discounts (7 tools)

list_coupons, get_coupon, create_coupon, update_coupon, delete_coupon, list_volume_discounts, list_sale_discounts

Inventory (3 tools)

list_locations, get_location, create_location

Automotive MMY (4 tools)

list_mmy_level1, list_mmy_level2, list_mmy_level3, list_mmy_level4

Example Prompts

"Show me all orders from today"
"Find products with SKU starting with 'BRAKE'"
"Create a new order for customer john@example.com"
"What's the stock level for product ID 123?"
"List all categories with their product counts"
"Add tracking number UPS123456 to order 789"
"Find customers who haven't ordered in 30 days"

Docker Compose Example

version: '3.8'
services:
  xcart-mcp:
    image: andrewkomkov/xcart-mcp
    ports:
      - "3000:3000"
    environment:
      - XCART_API_URL=https://your-store.com
      - XCART_API_KEY=${XCART_API_KEY}
      - XCART_ROLE=admin
      - MCP_TRANSPORT=sse
      - MCP_ACCESS_TOKEN=${MCP_ACCESS_TOKEN}
      - MCP_RATE_LIMIT=100
    restart: unless-stopped

Troubleshooting

SSE Connection Issues

If using mcp-remote and getting timeouts:

1. Ensure you use --transport sse-only flag
2. Use IP address instead of localhost (e.g., 127.0.0.1)
3. Check firewall allows port 3000

Node.js Version Issues

If you see ReadableStream is not defined:

• Update Node.js to version 18+
• Or use full path to modern npx in Claude Desktop config

Integration Guide

See for:

• Architecture diagrams
• Python, Node.js, LangChain examples
• Telegram Bot example
• All tools reference

License

MIT License

Support

• Docker Hub: https://hub.docker.com/r/andrewkomkov/xcart-mcp
• X-Cart Documentation: https://help.x-cart.com
• X-Cart Support: https://support.x-cart.com