mcpengine/servers/lightspeed/README.md

Lightspeed MCP Server

A comprehensive Model Context Protocol (MCP) server for Lightspeed POS and eCommerce platform integration. This server provides extensive tools for managing retail and restaurant operations including products, inventory, customers, sales, orders, employees, and more.

Overview

Lightspeed is a cloud-based POS and eCommerce platform used by retailers and restaurants worldwide. This MCP server provides AI assistants with direct access to Lightspeed's API, enabling automated store management, inventory control, sales analysis, and customer relationship management.

Features

🛍️ Product Management

• 60+ MCP Tools covering all aspects of retail/restaurant operations
• Full CRUD operations for products, inventory, customers, sales, and orders
• Advanced search and filtering capabilities
• Bulk operations support

📊 Analytics & Reporting

• Real-time sales dashboards
• Inventory valuation and stock reports
• Customer analytics and segmentation
• Employee performance tracking
• Top products and revenue analysis

💼 Business Operations

• Purchase order management
• Supplier relationship management
• Discount and promotion tools
• Loyalty program integration
• Multi-location support

🎨 16 React Applications

Beautiful, dark-themed UI applications for:

• Product browsing and management
• Inventory dashboard and tracking
• Customer relationship management
• Sales analytics and reporting
• Purchase order processing
• Employee performance monitoring
• Category hierarchymanagement
• Discount creation and management
• Loyalty program dashboard
• Analytics suite with visualizations
• POS simulator for testing
• Quick sale interface
• Stock transfer between locations
• Price management tools
• Supplier portal
• Tax calculation utilities

Installation

npm install @mcpengine/lightspeed-mcp-server

Or install from source:

git clone https://github.com/mcpengine/mcpengine
cd mcpengine/servers/lightspeed
npm install
npm run build

Configuration

Environment Variables

Create a .env file or export these environment variables:

# Required
LIGHTSPEED_ACCOUNT_ID=123456        # Your Lightspeed account ID
LIGHTSPEED_API_KEY=your_api_key_here # Your Lightspeed API key

# Optional
LIGHTSPEED_API_SECRET=secret         # API secret (if required)
LIGHTSPEED_BASE_URL=https://api.lightspeedapp.com/API/V3 # Custom API URL
LIGHTSPEED_TYPE=retail               # "retail" or "restaurant"

Getting Lightspeed API Credentials

1. Log into your Lightspeed account
2. Navigate to Settings → API Management
3. Create a new API key
4. Copy your Account ID and API Key
5. Set the appropriate permissions for your use case

Usage

As MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "lightspeed": {
      "command": "lightspeed-mcp",
      "env": {
        "LIGHTSPEED_ACCOUNT_ID": "123456",
        "LIGHTSPEED_API_KEY": "your_api_key_here"
      }
    }
  }
}

Standalone

# Set environment variables
export LIGHTSPEED_ACCOUNT_ID=123456
export LIGHTSPEED_API_KEY=your_api_key_here

# Run the server
lightspeed-mcp

Development Mode

npm run dev

Available Tools

Products (7 tools)

• lightspeed_list_products - List all products with pagination and filtering
• lightspeed_get_product - Get single product details
• lightspeed_create_product - Create new product
• lightspeed_update_product - Update existing product
• lightspeed_delete_product - Delete product
• lightspeed_archive_product - Archive product (soft delete)
• lightspeed_search_products_by_sku - Search by SKU

Inventory (6 tools)

• lightspeed_get_product_inventory - Get inventory levels across locations
• lightspeed_update_inventory - Set inventory quantity
• lightspeed_adjust_inventory - Adjust inventory by relative amount
• lightspeed_set_reorder_point - Configure low stock alerts
• lightspeed_check_low_stock - Find products below reorder point
• lightspeed_inventory_transfer - Transfer stock between locations

Customers (7 tools)

• lightspeed_list_customers - List all customers
• lightspeed_get_customer - Get customer details
• lightspeed_create_customer - Add new customer
• lightspeed_update_customer - Update customer information
• lightspeed_delete_customer - Remove customer
• lightspeed_search_customers - Search by name, email, phone
• lightspeed_get_customer_by_email - Find customer by email

Sales & Transactions (8 tools)

• lightspeed_list_sales - List sales with date range filtering
• lightspeed_get_sale - Get sale details with line items
• lightspeed_create_sale - Create new sale
• lightspeed_update_sale - Update sale
• lightspeed_void_sale - Void transaction
• lightspeed_get_sales_by_customer - Customer purchase history
• lightspeed_get_sales_by_employee - Employee sales performance
• lightspeed_calculate_daily_sales - Daily sales totals

Orders (7 tools)

• lightspeed_list_orders - List purchase orders
• lightspeed_get_order - Get order details
• lightspeed_create_order - Create purchase order
• lightspeed_update_order - Update order
• lightspeed_delete_order - Delete order
• lightspeed_receive_order - Mark order as received
• lightspeed_cancel_order - Cancel purchase order

Employees (6 tools)

• lightspeed_list_employees - List all employees
• lightspeed_get_employee - Get employee details
• lightspeed_create_employee - Add new employee
• lightspeed_update_employee - Update employee
• lightspeed_delete_employee - Remove employee
• lightspeed_search_employees - Search employees

Categories (6 tools)

• lightspeed_list_categories - List all categories
• lightspeed_get_category - Get category details
• lightspeed_create_category - Create new category
• lightspeed_update_category - Update category
• lightspeed_delete_category - Delete category
• lightspeed_get_category_tree - Get category hierarchy

Suppliers (6 tools)

• lightspeed_list_suppliers - List all suppliers
• lightspeed_get_supplier - Get supplier details
• lightspeed_create_supplier - Add new supplier
• lightspeed_update_supplier - Update supplier
• lightspeed_delete_supplier - Remove supplier
• lightspeed_search_suppliers - Search suppliers

Discounts (6 tools)

• lightspeed_list_discounts - List all discounts
• lightspeed_get_discount - Get discount details
• lightspeed_create_discount - Create percentage or fixed discount
• lightspeed_update_discount - Update discount
• lightspeed_delete_discount - Remove discount
• lightspeed_get_active_discounts - Get currently active discounts

Loyalty Programs (5 tools)

• lightspeed_get_customer_loyalty - Get customer loyalty points
• lightspeed_add_loyalty_points - Add points to customer
• lightspeed_redeem_loyalty_points - Redeem customer points
• lightspeed_calculate_loyalty_points - Calculate points for purchase
• lightspeed_get_top_loyalty_customers - Find top loyalty members

Reporting & Analytics (5 tools)

• lightspeed_sales_report - Comprehensive sales report with metrics
• lightspeed_inventory_report - Inventory valuation and stock levels
• lightspeed_customer_report - Customer acquisition and retention
• lightspeed_employee_performance - Employee sales performance
• lightspeed_top_selling_products - Best selling products analysis

Shops & Configuration (7 tools)

• lightspeed_list_shops - List all shop locations
• lightspeed_get_shop - Get shop details
• lightspeed_list_registers - List POS registers
• lightspeed_get_manufacturers - List manufacturers
• lightspeed_create_manufacturer - Add manufacturer
• lightspeed_get_tax_categories - List tax categories
• lightspeed_get_payment_types - List payment types

Total: 66 MCP Tools

React Applications

All applications feature a modern dark theme (bg-gray-900) and responsive design:

1. Product Browser - Search and browse product catalog
2. Inventory Dashboard - Real-time stock levels and alerts
3. Customer Manager - CRM and customer database
4. Sales Dashboard - Sales metrics and analytics
5. Order Manager - Purchase order tracking
6. Employee Tracker - Employee management and performance
7. Category Editor - Manage category hierarchy
8. Discount Creator - Create and manage promotions
9. Loyalty Dashboard - Loyalty program overview
10. Analytics Suite - Advanced analytics and visualizations
11. POS Simulator - Test POS transactions
12. Quick Sale - Rapid sale entry interface
13. Stock Transfer - Inter-location inventory transfers
14. Price Manager - Bulk price management
15. Supplier Portal - Supplier relationship management
16. Tax Calculator - Tax calculation utilities

Access apps at: dist/ui/{app-name}/index.html after building.

API Coverage

This server supports both Lightspeed Retail (X-Series) and Restaurant (R-Series) platforms:

Retail X-Series

• Products (Items)
• Inventory (ItemShops)
• Customers
• Sales
• Purchase Orders
• Employees
• Categories
• Suppliers (Vendors)
• Discounts
• Shops & Registers

Restaurant R-Series

Compatible with most endpoints; specific R-Series features coming soon.

Development

Project Structure

lightspeed/
├── src/
│   ├── clients/
│   │   └── lightspeed.ts      # API client
│   ├── types/
│   │   └── index.ts           # TypeScript types
│   ├── tools/
│   │   ├── products.ts        # Product tools
│   │   ├── inventory.ts       # Inventory tools
│   │   ├── customers.ts       # Customer tools
│   │   ├── sales.ts           # Sales tools
│   │   ├── orders.ts          # Order tools
│   │   ├── employees.ts       # Employee tools
│   │   ├── categories.ts      # Category tools
│   │   ├── suppliers.ts       # Supplier tools
│   │   ├── discounts.ts       # Discount tools
│   │   ├── loyalty.ts         # Loyalty tools
│   │   ├── reporting.ts       # Reporting tools
│   │   └── shops.ts           # Shop tools
│   ├── ui/
│   │   └── react-app/         # 16 React applications
│   ├── server.ts              # MCP server setup
│   └── main.ts                # Entry point
├── dist/                      # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

This compiles TypeScript and builds all React applications.

Testing

# Test with MCP Inspector
npx @modelcontextprotocol/inspector lightspeed-mcp

# Or use the MCP CLI
mcp dev lightspeed-mcp

Use Cases

Inventory Management

"Check which products are low on stock and create purchase orders for them"

Customer Analytics

"Show me the top 10 customers by total spend this month"

Sales Reporting

"Generate a sales report for last week broken down by employee"

Product Management

"Create a new product in the Electronics category with a 20% markup"

Multi-Location Operations

"Transfer 50 units of SKU-12345 from Store A to Store B"

Promotion Management

"Create a 15% discount for orders over $100 valid for the next 7 days"

Error Handling

All tools return a consistent response format:

{
  success: true,
  data: { /* result */ }
}

// or

{
  success: false,
  error: "Error message",
  details: { /* additional info */ }
}

Rate Limiting

Lightspeed API has rate limits. This server respects those limits:

• Default: 5 requests/second
• Burst: 10 requests/second
• Daily: 10,000 requests

Security

• Never commit API keys to version control
• Use environment variables for credentials
• Restrict API permissions to minimum required
• Enable IP whitelisting in Lightspeed if possible
• Rotate API keys regularly

Troubleshooting

"Missing required environment variables"

Ensure LIGHTSPEED_ACCOUNT_ID and LIGHTSPEED_API_KEY are set.

"API request failed"

• Verify API credentials are correct
• Check account ID matches your Lightspeed account
• Ensure API key has necessary permissions
• Check API rate limits

"Tool not found"

Update to the latest version and rebuild:

npm update @mcpengine/lightspeed-mcp-server
npm run build

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: https://github.com/mcpengine/mcpengine/issues
• Docs: https://mcpengine.dev/servers/lightspeed
• Discord: https://discord.gg/mcpengine

Changelog

v1.0.0 (2024)

• Initial release
• 66 MCP tools covering all major Lightspeed entities
• 16 React applications with dark theme
• Full TypeScript support
• Comprehensive error handling
• Multi-location support
• Retail and Restaurant platform compatibility

Related Projects

• MCP Engine - MCP server factory
• Lightspeed API Docs - Official API documentation
• Model Context Protocol - MCP specification

---

Built with ❤️ by MCPEngine

For more MCP servers, visit mcpengine.dev