CS-Cart MCP Server

A Model Context Protocol (MCP) server that provides comprehensive tools for managing CS-Cart e-commerce stores, including product management, order handling, and sales analytics.

Features

Product Management

get_products: Retrieve product listings with filtering and pagination
get_product: Get detailed product information
create_product: Add new products to the store
update_product: Modify existing product details
delete_product: Remove products from the store
update_product_stock: Update product inventory levels

Order Management

get_orders: Retrieve order listings with various filters
get_order: Get detailed order information
update_order_status: Change order status and notify customers

Category Management

get_categories: Retrieve product categories and subcategories

User Management

get_users: Get customer and user information

Analytics

get_sales_statistics: Retrieve sales data and statistics

Installation

Option 1: Quick Setup (Recommended)

Clone this repository:

git clone <repository-url>
cd cscart-mcp-server

Run the setup script:

npm run setup

Install dependencies:

npm install

Update .env with your CS-Cart credentials and start:

npm start

Option 2: Manual Local Installation

Clone this repository:

git clone <repository-url>
cd cscart-mcp-server

Install dependencies:

npm install

Configure environment variables:

cp .env.example .env

Edit .env with your CS-Cart API credentials:

CSCART_API_URL=https://your-store.com/api
CSCART_API_EMAIL=admin@yourstore.com
CSCART_API_KEY=your-api-key-here

Option 2: Docker Installation

Clone this repository:

git clone <repository-url>
cd cscart-mcp-server

Configure environment variables:

cp .env.example .env

Build and run with Docker Compose:

docker-compose up -d

Or build and run with Docker:

# Build the image
docker build -t cscart-mcp-server .

# Run the container
docker run -d \
  --name cscart-mcp-server \
  --env-file .env \
  cscart-mcp-server

Option 3: Production Docker Build

For production deployment with optimized image:

# Build production image
docker build -f Dockerfile.production -t cscart-mcp-server:prod .

# Run production container
docker run -d \
  --name cscart-mcp-server-prod \
  --env-file .env \
  --restart unless-stopped \
  cscart-mcp-server:prod

CS-Cart API Setup

Enable API Access:
- Log into your CS-Cart admin panel
- Go to Administration → API access
- Enable API access for your store
Generate API Key:
- Create a new API key or use existing one
- Note the API key and admin email for configuration
API Permissions:
- Ensure the API user has appropriate permissions for:
  - Products (read/write)
  - Orders (read/write)
  - Categories (read)
  - Users (read)
  - Statistics (read)

Usage

Running the Server

Quick Commands

# Setup project
npm run setup

# Development
npm run dev

# Production
npm start

# Docker commands
npm run docker:build      # Build standard image
npm run docker:build:prod # Build production image
npm run docker:run        # Start with docker-compose
npm run docker:stop       # Stop docker-compose
npm run docker:logs       # View logs

Docker Deployment

Start with Docker Compose:

docker-compose up -d

View logs:

docker-compose logs -f cscart-mcp-server

Stop the service:

docker-compose down

Production Deployment

For production use the optimized Dockerfile:

docker build -f Dockerfile.production -t cscart-mcp-server:latest .
docker run -d \
  --name cscart-mcp-prod \
  --env-file .env \
  --restart unless-stopped \
  --memory=512m \
  --cpus=0.5 \
  cscart-mcp-server:latest

Integration with MCP Clients

Add this server to your MCP client configuration. For example, with Claude Desktop:

{
  "mcpServers": {
    "cscart": {
      "command": "node",
      "args": ["/path/to/cscart-mcp-server/src/index.js"],
      "env": {
        "CSCART_API_URL": "https://your-store.com/api",
        "CSCART_API_EMAIL": "admin@yourstore.com",
        "CSCART_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: Use the full path to the node executable. Common paths:

macOS: /usr/local/bin/node or /opt/homebrew/bin/node
Linux: /usr/bin/node or /usr/local/bin/node
Windows: C:\\Program Files\\nodejs\\node.exe

Integration with AnythingLLM

To integrate this MCP server with AnythingLLM:

Navigate to AnythingLLM Settings:
- Open your AnythingLLM instance
- Go to Settings → Integrations → MCP Servers

Add the CS-Cart MCP Server:

{
  "command": "/usr/local/bin/node",
  "args": ["/full/path/to/cscart-mcp-server/src/index.js"],
  "env": {
    "CSCART_API_URL": "https://your-store.com/api",
    "CSCART_API_EMAIL": "admin@yourstore.com",
    "CSCART_API_KEY": "your-api-key-here"
  }
}

Important Path Notes:
- Use the full absolute path to the node executable
- Use the full absolute path to the src/index.js file
- Ensure the paths are accessible from the AnythingLLM container/environment

Example for macOS:

{
  "command": "/usr/local/bin/node",
  "args": ["/Users/username/GitHub/cscart-mcp/src/index.js"],
  "env": {
    "CSCART_API_URL": "https://your-store.com/api",
    "CSCART_API_EMAIL": "admin@yourstore.com",
    "CSCART_API_KEY": "your-api-key-here"
  }
}

Docker Integration (if AnythingLLM is running in Docker):
- Mount the CS-Cart MCP server directory as a volume
- Use the container path in the configuration
- Ensure proper file permissions
Test the Integration:
- Restart AnythingLLM after adding the MCP server
- Check the logs for any connection errors
- Try using CS-Cart tools in your conversations

Available Tools

Product Tools

get_products

Retrieve a list of products with optional filtering:

{
  "page": 1,
  "items_per_page": 10,
  "status": "A",
  "category_id": 123,
  "q": "search term"
}

create_product

Create a new product:

{
  "product": "Product Name",
  "price": 29.99,
  "category_ids": [123, 456],
  "description": "Short description",
  "full_description": "Full product description",
  "status": "A",
  "amount": 100
}

Order Tools

get_orders

Retrieve orders with filtering:

{
  "page": 1,
  "items_per_page": 10,
  "status": "P",
  "period": "M",
  "user_id": 123
}

update_order_status

Update order status:

{
  "order_id": 12345,
  "status": "C",
  "notify_user": true
}

Status Codes

Product Status:

A - Active
D - Disabled
H - Hidden

Order Status:

O - Open
P - Processed
C - Complete
F - Failed
D - Declined
B - Backordered
I - Incomplete

User Status:

A - Active
D - Disabled

User Types:

A - Admin
V - Vendor
C - Customer

Error Handling

The server includes comprehensive error handling:

API connection errors
Invalid parameters
Missing required fields
CS-Cart API errors

All errors are returned with descriptive messages to help with debugging.

Docker Configuration

Environment Variables

When using Docker, you can set environment variables in several ways:

Using .env file (recommended):

CSCART_API_URL=https://your-store.com/api
CSCART_API_EMAIL=admin@yourstore.com
CSCART_API_KEY=your-api-key-here
LOG_LEVEL=info

Using docker-compose.yml:

environment:
  - CSCART_API_URL=https://your-store.com/api
  - CSCART_API_EMAIL=admin@yourstore.com
  - CSCART_API_KEY=your-api-key-here

Using Docker run command:

docker run -d \
  -e CSCART_API_URL=https://your-store.com/api \
  -e CSCART_API_EMAIL=admin@yourstore.com \
  -e CSCART_API_KEY=your-api-key-here \
  cscart-mcp-server

Docker Images

Dockerfile: Standard development image (~200MB)
Dockerfile.production: Optimized production image (~150MB)
- Multi-stage build for smaller size
- Non-root user for security
- Proper signal handling with dumb-init
- Health checks included

Resource Limits

The docker-compose.yml includes resource limits:

CPU: 0.5 cores max, 0.25 cores reserved
Memory: 512MB max, 256MB reserved

Adjust these based on your server capacity and usage requirements.

Project Structure

cscart-mcp-server/
├── src/
│   └── index.js              # Main server file (moved here)
├── scripts/
│   └── setup.js              # Setup automation script
├── logs/                     # Log files directory
├── tests/                    # Test files directory
├── config/                   # Configuration files
├── package.json              # Updated paths
├── project.config.js         # Project configuration
├── Dockerfile               # Updated for new structure
├── Dockerfile.production    # Updated for new structure
├── docker-compose.yml       # Docker orchestration
├── .env.example             # Environment template
└── README.md                # Updated documentation

Adding New Tools

To add new tools, extend the ListToolsRequestSchema handler and add corresponding methods to the CSCartMCPServer class.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues related to:

CS-Cart API: Check CS-Cart documentation or support
MCP Protocol: Refer to MCP documentation
This Server: Open an issue in this repository

Changelog

v0.1.0

Initial release
Basic product management tools
Order management functionality
Category and user tools
Sales statistics support