mcpengine/servers/lightspeed

Lightspeed Retail MCP Server

Complete Model Context Protocol (MCP) server for Lightspeed Retail (X-Series/R-Series). Provides comprehensive point-of-sale, inventory management, and retail analytics capabilities for Claude Desktop and other MCP clients.

Features

🛍️ Products & Inventory

• List, create, update, and delete products
• Manage product variants and images
• Track inventory levels across shops
• Handle stock transfers and adjustments
• Purchase order management
• Supplier/vendor management

💰 Sales & Transactions

• Create and manage sales transactions
• Add line items to sales
• Process payments and refunds
• Track completed and pending sales
• Register/till management (open/close)

👥 Customers

• Customer database management
• Search and filter customers
• Track purchase history
• Loyalty program integration
• Contact information management

👔 Employees

• Employee roster management
• Time clock functionality (clock in/out)
• Employee sales performance tracking
• Role-based access control

📊 Reporting

• Sales summary reports
• Inventory valuation
• Product performance analysis
• Employee sales reports
• Custom date range filtering

⚙️ Configuration

• Product categories and hierarchies
• Discount and promotion management
• Tax class configuration
• Multi-location support

Installation

npm install @mcpengine/lightspeed-mcp-server

Configuration

Environment Variables

export LIGHTSPEED_ACCOUNT_ID=your_account_id
export LIGHTSPEED_ACCESS_TOKEN=your_oauth_token
# Optional: Custom API URL (defaults to official Lightspeed API)
export LIGHTSPEED_API_URL=https://api.lightspeedapp.com/API/V3/Account/YOUR_ACCOUNT

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["-y", "@mcpengine/lightspeed-mcp-server"],
      "env": {
        "LIGHTSPEED_ACCOUNT_ID": "your_account_id",
        "LIGHTSPEED_ACCESS_TOKEN": "your_oauth_token"
      }
    }
  }
}

OAuth Setup

Lightspeed uses OAuth2 for authentication. To get your access token:

1. Create Lightspeed API Application

   • Go to Lightspeed Developer Portal
   • Register a new application
   • Note your Client ID and Client Secret

2. Generate Access Token

   curl -X POST https://cloud.lightspeedapp.com/oauth/access_token.php \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "code=AUTHORIZATION_CODE" \
     -d "grant_type=authorization_code"
   

3. Get Account ID

   • Available in Lightspeed admin panel
   • Or via API: GET https://api.lightspeedapp.com/API/Account.json

Tools (54 Total)

Products (8 tools)

• lightspeed_list_products - List all products
• lightspeed_get_product - Get product details
• lightspeed_create_product - Create new product
• lightspeed_update_product - Update product
• lightspeed_delete_product - Delete/archive product
• lightspeed_list_product_variants - List product variants
• lightspeed_list_product_images - List product images
• lightspeed_update_product_inventory - Update inventory quantity

Sales (8 tools)

• lightspeed_list_sales - List sales transactions
• lightspeed_get_sale - Get sale details
• lightspeed_create_sale - Create new sale
• lightspeed_add_sale_line_item - Add item to sale
• lightspeed_list_sale_payments - List sale payments
• lightspeed_process_payment - Process payment
• lightspeed_refund_sale - Create refund
• lightspeed_complete_sale - Mark sale as complete

Customers (7 tools)

• lightspeed_list_customers - List all customers
• lightspeed_get_customer - Get customer details
• lightspeed_create_customer - Create new customer
• lightspeed_update_customer - Update customer
• lightspeed_delete_customer - Delete customer
• lightspeed_search_customers - Search customers
• lightspeed_get_customer_loyalty - Get loyalty info

Inventory (8 tools)

• lightspeed_list_inventory - List inventory counts
• lightspeed_get_item_inventory - Get item inventory
• lightspeed_update_inventory_count - Update inventory
• lightspeed_transfer_stock - Transfer between shops
• lightspeed_list_inventory_adjustments - List adjustments
• lightspeed_list_suppliers - List suppliers/vendors
• lightspeed_create_purchase_order - Create PO
• lightspeed_list_purchase_orders - List POs

Registers (5 tools)

• lightspeed_list_registers - List all registers
• lightspeed_get_register - Get register details
• lightspeed_open_register - Open register (till)
• lightspeed_close_register - Close register
• lightspeed_get_cash_counts - Get cash counts

Employees (6 tools)

• lightspeed_list_employees - List all employees
• lightspeed_get_employee - Get employee details
• lightspeed_create_employee - Create employee
• lightspeed_update_employee - Update employee
• lightspeed_list_time_entries - List time entries
• lightspeed_clock_in - Clock in employee
• lightspeed_clock_out - Clock out employee

Categories (5 tools)

• lightspeed_list_categories - List categories
• lightspeed_get_category - Get category details
• lightspeed_create_category - Create category
• lightspeed_update_category - Update category
• lightspeed_delete_category - Delete category

Discounts (5 tools)

• lightspeed_list_discounts - List discounts
• lightspeed_get_discount - Get discount details
• lightspeed_create_discount - Create discount
• lightspeed_update_discount - Update discount
• lightspeed_delete_discount - Delete discount

Taxes (4 tools)

• lightspeed_list_taxes - List tax classes
• lightspeed_get_tax - Get tax details
• lightspeed_create_tax - Create tax class
• lightspeed_update_tax - Update tax class

Reporting (4 tools)

• lightspeed_sales_summary - Sales summary report
• lightspeed_inventory_value - Inventory valuation
• lightspeed_product_performance - Product performance
• lightspeed_employee_sales - Employee sales report

MCP Apps (17 Apps)

Pre-built UI applications accessible via MCP prompts:

Products

• product-dashboard - Inventory overview
• product-detail - Detailed product view
• product-grid - Filterable product list
• category-manager - Category management

Sales

• sales-dashboard - Sales overview
• sales-detail - Transaction details
• sales-report - Sales analytics

Customers

• customer-detail - Customer profile
• customer-grid - Customer list

Inventory

• inventory-tracker - Stock levels
• inventory-adjustments - Adjustment tracking
• purchase-orders - PO management

Operations

• register-manager - Register management
• employee-dashboard - Employee overview
• discount-manager - Discount configuration
• tax-settings - Tax configuration
• product-performance - Performance analytics

Example Usage

// In Claude Desktop, you can now use natural language:

"Show me the product dashboard"
"Create a new customer named John Doe with email john@example.com"
"List all sales from yesterday"
"What are the top 10 selling products this month?"
"Transfer 50 units of item #123 from shop 1 to shop 2"
"Generate a sales summary report for last week"
"Clock in employee #456"
"Show me inventory levels for shop 1"

API Reference

Lightspeed API Documentation

• Official API Docs
• Authentication
• Rate Limits

Rate Limiting

• Default: 10 requests/second per account
• Burst: up to 60 requests
• This server includes automatic rate limit handling and retry logic

Development

# Clone repository
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/lightspeed

# Install dependencies
npm install

# Build
npm run build

# Run locally
export LIGHTSPEED_ACCOUNT_ID=your_account_id
export LIGHTSPEED_ACCESS_TOKEN=your_token
npm start

Troubleshooting

Authentication Errors

• Verify your Account ID and Access Token are correct
• Check if your OAuth token has expired (Lightspeed tokens expire)
• Ensure your API application has the required scopes

API Errors

• Check Lightspeed API status page
• Verify rate limits haven't been exceeded
• Ensure your account has access to the requested resources

Connection Issues

• Verify network connectivity
• Check firewall settings
• Ensure API URL is correct (if using custom URL)

License

MIT

Support

• GitHub Issues: mcpengine/issues
• Lightspeed Support: support.lightspeedhq.com

Related Resources

• Lightspeed Developer Portal
• MCP Protocol Specification
• Claude Desktop Documentation